docs: improve /create-adr command — adr-tools inspiration, superseding flow, Nygard best practices

.claude/commands/create-adr.md

@@ -2,6 +2,8 @@
 
 Use this command when you need to document an architectural decision made during a task.
 
+Inspired by [adr-tools](https://github.com/npryce/adr-tools) (Nygard format), adapted for Laputa's frontmatter-based note format.
+
 ## When to use this
 
 Create an ADR when your work involves any of these:
@@ -13,21 +15,21 @@ Create an ADR when your work involves any of these:
 
 Do NOT create ADRs for: bug fixes, UI styling, refactors that preserve behavior, or test additions.
 
-## Steps
+## Creating a new ADR
 
-### 1. Find the next available ID
+### 1. Find the next ID
 
 ```bash
-ls docs/adr/*.md | grep -oP '\d{4}' | sort | tail -1
+ls docs/adr/*.md | grep -oP '\d{4}' | sort -n | tail -1 | xargs -I{} printf '%04d\n' $(({} + 1))
 ```
 
-Increment by 1. If no files exist, start at `0001`.
+If no files exist yet, start at `0001`.
 
 ### 2. Create the file
 
 Filename: `docs/adr/NNNN-short-kebab-title.md`
 
-Use this template exactly:
+Template:
 
 ```markdown
 ---
@@ -39,57 +41,93 @@ date: YYYY-MM-DD
 ---
 
 ## Context
-What situation led to this decision? What forces and constraints are at play?
+
+The issue motivating this decision, and any context that influences or constrains it.
 
 ## Decision
-**What was decided.** State it clearly in one or two sentences — bold so it stands out.
+
+**The change we're proposing or have agreed to implement.** State it clearly in one or two sentences — bold so it stands out.
 
 ## Options considered
+
 - **Option A** (chosen): brief description — pros / cons
 - **Option B**: brief description — pros / cons
 - **Option C**: brief description — pros / cons
 
 ## Consequences
+
 What becomes easier or harder as a result?
-What are the positive and negative ramifications?
+What risks does this introduce that will need to be mitigated?
 What would trigger re-evaluation of this decision?
 
 ## Advice
-*(optional)* Input received before making this decision.
+
+*(optional)* Input received before making this decision — who was consulted, what they said.
 Omit this section if the decision was made without external input.
 ```
 
 ### 3. Update the index
 
-Add a row to the table in `docs/adr/README.md`:
+Add a row to `docs/adr/README.md`:
 
 ```markdown
 | [NNNN](NNNN-short-kebab-title.md) | Title | active |
 ```
 
-### 4. Commit in the same commit as the feature
-
-Include the ADR in the same commit as the code it documents:
+### 4. Include in the same commit as the feature
 
 ```bash
-git add docs/adr/NNNN-short-kebab-title.md docs/adr/README.md
-# include in the feature commit, not a separate one
+git add docs/adr/NNNN-*.md docs/adr/README.md
+# fold into the feature commit — do not create a separate commit just for the ADR
 ```
 
+---
+
 ## Superseding an existing ADR
 
-If your decision replaces an existing one:
+Equivalent of `adr new -s <N>` from adr-tools — do this in two steps:
 
-1. Edit the existing ADR — add `superseded_by: "NNNN"` to frontmatter and change `status: superseded`
-2. Create the new ADR with the updated decision
-3. Update the README index (change old status to `superseded`, add new row)
+### Step 1: Mark the old ADR as superseded
 
-**Never edit the content of an active ADR** — only its status metadata.
+Edit the existing file — add `superseded_by` and update `status`:
 
-## Best practices
+```yaml
+---
+type: ADR
+id: "000N"
+title: "Old decision title"
+status: superseded          # ← change from active
+superseded_by: "NNNN"       # ← add this
+date: YYYY-MM-DD
+---
+```
 
-- Write the **Decision** section first — if you can't state it in 1-2 sentences, the decision is too vague
-- Be honest about **Options considered** — document the alternatives you actually thought about, not hypothetical ones
-- **Consequences** should include both positive and negative — a one-sided ADR is a red flag
-- Date = today's date in `YYYY-MM-DD` format
-- If you're unsure whether something warrants an ADR, err on the side of creating one — it's cheaper to have an unnecessary ADR than to lose context
+**Never edit the content sections** of an active ADR — only the status metadata.
+
+### Step 2: Create the new ADR
+
+Follow the steps above. In the **Context** section, reference the superseded ADR:
+
+```markdown
+## Context
+
+Supersedes [ADR-000N](000N-old-title.md).
+
+[explain why the old decision no longer holds]
+```
+
+### Step 3: Update the README index
+
+Change the old row's status to `superseded`, add the new row.
+
+---
+
+## Best practices (from adr-tools / Nygard)
+
+- **One decision per ADR** — if you find yourself writing "and also", split it
+- **Write Decision first** — if you can't state it in 1-2 sentences, the decision is too vague
+- **Context is the "why now"** — what forced this decision to be made today?
+- **Consequences should include negatives** — a one-sided ADR is a red flag
+- **Committed = immutable** — once pushed, the content doesn't change; only status metadata does
+- **If in doubt, create one** — cheaper to have an unnecessary ADR than to lose context
+- Date = today's date, `YYYY-MM-DD`