---
name: dld-decide
description: Record a single development decision as a markdown file with YAML frontmatter. Collects context, rationale, and code references interactively.
compatibility: Requires Node.js 22+ and git.
metadata:
  dld-kit-version: "1.0.0"
---
<!-- Generated by dld-kit from templates/skills/dld-decide/SKILL.md. Do not edit: updating the skills overwrites this file. -->

# /dld-decide — Record a Decision

You are helping the developer record a development decision. This should be a focused, low-ceremony conversation — not an interrogation.

## Interaction style

Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user rather than waiting for freeform replies.

## Commands

The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 22+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`.

This skill uses: `next-id`, `create-decision`, `find-missing-amends`, `update-status`, `check-decision-edits`, `restore-decision-prose`, `regenerate-index`.

## Prerequisites

Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.

## Read project context

1. Read `dld.config.yaml` to understand the project structure (flat vs namespaced, decisions directory, namespaces list)
2. Read `decisions/PRACTICES.md` if it exists — be aware of project conventions when helping structure the decision
3. For namespaced projects, also read `decisions/records/<namespace>/PRACTICES.md` if it exists for the relevant namespace

## Conversation flow

### 1. Collect the decision

If the user provided context with the skill invocation, use it. Otherwise ask:

> What decision are you recording? Tell me what you decided, why, and what code it affects.

Listen for:
- **What** was decided (the decision itself)
- **Why** (the rationale — what problem it solves, what alternatives were considered)
- **What it affects** (code areas, components, modules)

### 2. Ask clarifying questions (if needed)

Only ask follow-up questions if the rationale or scope is genuinely unclear. Maximum 3-5 questions total. Don't interrogate — if the developer gave enough context, move on.

Good reasons to ask:
- The rationale is missing or unclear
- There might be alternatives worth noting
- The scope of affected code isn't clear
- There are obvious consequences worth recording

### 3. Check for related decisions

Scan existing decision files for potential relationships:
- Decisions that reference the same code paths
- Decisions with overlapping tags
- Decisions that this one might supersede or amend

If you find related decisions, mention them and ask whether this decision **supersedes** (fully replaces) or **amends** (partially modifies) any of them. A superseded decision gets marked as `superseded` and is no longer active. An amended decision stays `accepted` — the amendment changes part of its scope while the rest remains in effect.

### 4. Determine namespace (namespaced projects only)

If the project is namespaced, determine which namespace this decision belongs to. Infer from the code references if possible, otherwise ask.

### 5. Assign ID

Run `next-id`:
```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" next-id
```

This outputs the next available ID (e.g., `DL-004`).

### 6. Create the decision record

Compose the markdown body with the relevant sections (Context, Decision, Rationale, Consequences). Omit sections that aren't relevant, but always include Context and Decision.

Then run `create-decision`, passing the body on stdin through a quoted heredoc:
```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" create-decision \
  --id "DL-NNN" \
  --title 'Short descriptive title' \
  --namespace "billing" \
  --tags 'tag1, tag2' \
  --supersedes "DL-003, DL-007" \
  --amends "DL-005" \
  --body-stdin <<'DLD_BODY'
## Context

What prompted this decision.

## Decision

What was decided.

## Rationale

Why this choice.

## Consequences

What becomes easier or harder.
DLD_BODY
```

Keep the delimiter quoted (`<<'DLD_BODY'`): that passes the body through exactly as written, so backticks, `$` and `%` in it need no escaping. Don't indent the body, and put the closing `DLD_BODY` alone on its own line, unindented; no line of the body may be exactly `DLD_BODY`. The other arguments are ordinary shell strings: put the title and tags in single quotes, and write an apostrophe in them as `'\''`.

Flags `--namespace`, `--tags`, `--supersedes`, `--amends` are optional. Pass `--namespace` only in a namespaced project, with one of the namespaces in `dld.config.yaml`; leave it out in a flat project, where it is an error. The command creates the file with YAML frontmatter and the body content, and outputs the file path.

If this decision supersedes others, also update their status:
```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" update-status DL-003 superseded
```

**Do not** update the status of amended decisions — they stay `accepted`.

**Check for unstated relationships.** `create-decision` warns on stderr (`Warning: DL-NNN: the body says it amends DL-XXX, but --amends does not list it`) when the body states a relationship its flags leave out. After creating the record, also run:

```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" find-missing-amends DL-NNN
```

Each line is `<source-id>:<referenced-id><TAB><tier>`. If it prints nothing, continue.

- `explicit`: the body says the new decision amends or supersedes DL-XXX. If it does, add DL-XXX to the record's `amends` or `supersedes` list (the record is a new draft, so edit its frontmatter directly), and for `supersedes` also run `node "<skill-dir>/../dld-common/scripts/dld.mjs" update-status DL-XXX superseded`. If the sentence doesn't describe a real relationship, reword it.
- `cue`: the body mentions DL-XXX in a sentence with a change word such as "replaces" or "no longer". Ask the user with `AskUserQuestion` whether the new decision amends DL-XXX, supersedes it, or only cites it, and update the frontmatter to match. For supersedes, also run `node "<skill-dir>/../dld-common/scripts/dld.mjs" update-status DL-XXX superseded`.

### 7. Check edits to decisions on the base branch

```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" check-decision-edits --uncommitted
```

This lists decisions that are already on the base branch and whose prose (the body below the frontmatter), `id` or `timestamp` has uncommitted changes, or that were deleted. Drafts (decisions not on the base branch yet, or still `proposed` there), changes to other frontmatter fields and edits already committed are never listed. If it prints nothing, continue. If a listed edit isn't yours (the user made it by hand), leave it alone and mention it.

Otherwise follow `decision_edits` in `dld.config.yaml` (default `block`; the command then exits 3):

- `block`: put the prose back with `node "<skill-dir>/../dld-common/scripts/dld.mjs" restore-decision-prose --uncommitted DL-NNN ...`, which also restores `id` and `timestamp` and keeps other frontmatter changes. If the change is still needed, record it as a new decision that amends or supersedes the old one (`/dld-decide`), and tell the user.
- `ask`: for each listed decision, ask the user with `AskUserQuestion` whether to keep the edit. Restore the ones they don't keep.
- `allow`: keep the edits and list them in your report.

If the command can't find the base branch, tell the user and continue. Its message says what it tried; setting `base_branch` in `dld.config.yaml` fixes it when the branch decisions merge into is not found automatically.

### 8. Regenerate INDEX.md

```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
```

### 9. Suggest next steps

> Decision **DL-NNN** recorded as `proposed`.
>
> Next steps:
> - `/dld-adjust` — refine the decision before implementing
> - `/dld-implement DL-NNN` — implement this decision
> - `/dld-decide` — record another decision