---
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 20+ and git.
metadata:
  dld-kit-version: "1.0.0-rc.4"
---
<!-- 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 20+. `<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`, `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`, piping the body via `printf` with `\n` for newlines (do **not** use literal newlines in the body argument — use `\n` escape sequences so the entire command stays on one logical line):
```bash
printf "## Context\n\nWhat prompted this decision.\n\n## Decision\n\nWhat was decided.\n\n## Rationale\n\nWhy this choice.\n\n## Consequences\n\nWhat becomes easier or harder." | 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
```

Flags `--namespace`, `--tags`, `--supersedes`, `--amends` are optional. The command creates the file with YAML frontmatter and the body content, and outputs the file path.

> **Note:** If the body contains literal `%` characters, escape them as `%%` (printf format string requirement).

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`.

### 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.

### 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