new-adr

name	new-adr
description	Use this skill when the user asks to create, write, draft, or open a new ADR (architecture decision record). Triggers on phrases like "new ADR", "write an ADR for…", "record this decision", "let's ADR this". Do NOT use for RFCs (use `new-rfc`) or for the phased build plan (that's docs/PLAN.md).

Skill: new-adr

Create a new ADR in docs/adr/ with the next sequential number.

When to invoke

The user wants to record an architectural decision. Before invoking, confirm:

1. The decision is about architecture or shared infrastructure, not a single phase's internals (that's a PLAN.md section update, not an ADR).
2. The decision has been made or formally proposed. ADRs are not a venue for open-ended discussion — that's an RFC.
3. There is a concrete tradeoff — at least one viable alternative was considered. If there's only one option, you don't need an ADR.

If any of these checks fail, push back rather than proceeding.

Procedure

1. Create docs/adr/ if it doesn't exist yet:

   mkdir -p docs/adr
   

2. Find the next number:

   ls docs/adr/ | grep -E '^[0-9]{4}' | sed 's/-.*//' | sort -n | tail -1
   

   Add 1, zero-pad to 4 digits. If no ADRs exist yet, start at 0001.

3. Pick a kebab-case title from the user's description. Keep it short and declarative: 0001-use-lasso-for-string-interning.md, not 0001-decision-about-strings.md.

4. Create the file with this structure:

   # ADR-NNNN: <Title>
   
   **Status:** Proposed
   **Date:** YYYY-MM-DD
   **Deciders:** <name(s)>
   
   ## Context
   
   <What is the situation that forces a decision? What constraints apply?
   What would happen if we did nothing?>
   
   ## Decision
   
   <One declarative sentence stating what we decided. Then elaborate.>
   
   ## Consequences
   
   **Positive:** <what gets better>
   **Negative:** <what we're giving up or accepting — be honest>
   
   ## Alternatives considered
   
   - **<Alternative A>** — rejected because <reason>.
   - **<Alternative B>** — rejected because <reason>.
   

5. Help the user draft the four sections. Push back if any section is empty or hand-wavy:

   • Context with no constraints listed → ask what's actually constraining this choice.
   • Decision without a single declarative sentence at the top → write one.
   • Consequences without honest negatives → ask what we're giving up.
   • Alternatives without rejection reasons → ask why each was rejected.

6. Create or update docs/adr/README.md to add the new ADR to a table:

   | ADR | Title | Status |
   | --- | ----- | ------ |
   | [ADR-0001](0001-<title>.md) | <title> | Proposed |
   

7. Tell the user to mark the ADR Accepted (and commit) once the relevant reviewers have signed off.

Anti-patterns to refuse

• "Make this ADR say we're definitely using X" before discussion has happened → that's an RFC, not an ADR. Suggest opening one instead.
• Editing an existing accepted ADR's body → ADRs are immutable after acceptance. If a decision is being reversed, write a new ADR that supersedes it, and update the old ADR's status to Superseded by ADR-NNNN (status only — leave the body untouched).