'* — decision: *<one-line summary>*. Does that framing look right?" This avoids a full redraft if the angle is wrong. ## 4. Determine the next ADR number ```bash ls adrs/[0-9]*.md 2>/dev/null | sort | tail -1 ``` Parse the numeric prefix from the last file (e.g. `0003` from `0003-use-sqlite.md`). Increment by one. If no files exist, start at `0001`. ## 5. Derive the filename Use the decision title in lowercase kebab-case: ``` adrs/<NNNN>-<kebab-title>.md ``` Example: `adrs/0004-store-adrs-in-top-level-folder.md` ## 6. Write the ADR Use this template — keep each section concise (a few sentences to a short paragraph): ```markdown # <NNNN>. <Title> Date: <YYYY-MM-DD> Status: <Accepted | Proposed | Deprecated | Superseded by [NNNN](<link>)> ## Context What situation, constraint, or requirement forced this decision? What was the problem space? ## Decision What was chosen and why? State it directly. ## Alternatives Considered What else was evaluated and why was it not chosen? This is the most important section for future readers — capture each rejected option and the specific reason it lost. ## Consequences What gets easier? What gets harder? What is accepted as a trade-off? ``` **Status values:** - `Accepted` — decision is in effect - `Proposed` — under discussion, not yet finalised - `Deprecated` — no longer relevant but not replaced - `Superseded by [NNNN](NNNN-<title>.md)` — replaced by a later ADR; also update the superseding ADR to note `Supersedes [NNNN]` **What belongs here:** - The reasoning and alternatives considered (with reasons each was rejected) - Constraints that shaped the choice (team size, existing tooling, latency requirements, etc.) - Known trade-offs being accepted **What does not belong here:** - Implementation steps or how-to instructions - Code snippets (unless a tiny illustrative example) - Anything derivable from reading the code ## 7. Present the draft for approval Show the full ADR text and ask for approval or changes before writing. This is a permanent record — it should be accurate. ## 8. Write the file Use the Write tool to create the file with the approved content. ## 9. Report back Tell the user the file path. Offer to stage and commit the file so the decision is captured in git history alongside the code it relates to.

--- disable-model-invocation: true name: adr description: Capture an Architecture Decision Record (ADR) for a significant decision made in the current project. Store in the project's adrs/ folder. Use when the user asks to record a decision, log an ADR, or capture why something was built a certain way. PROACTIVELY suggest capturing an ADR whenever a non-obvious architectural choice is made — technology selection, structural trade-offs, rejected alternatives — especially after a discussion where context and reasoning were developed. A good prompt — "Want me to capture this as an ADR?" --- # ADR Skill Captures a decision as an Architecture Decision Record in the project's ADR directory. ADRs record the *why* — context, the decision made, alternatives rejected, and consequences — not implementation details. ## 1. Resolve the project root and ADR directory The project root is the working directory. Check for an existing ADR directory before creating one: ```bash ls -d adrs/ docs/adr/ docs/decisions/ architecture/decisions/ 2>/dev/null | head -1 ``` Use whichever exists. If none exist, default to `adrs/` and create it: ```bash mkdir -p adrs ``` ## 2. Check for existing ADR format If ADR files exist, read the most recent one to match its format and section naming exactly. Don't impose a different structure on a project that already has a convention. ## 3. Confirm the title and framing before drafting Before writing a full ADR, confirm with the user in one sentence: > "I'll capture this as: *''* — decision: *<one-line summary>*. Does that framing look right?" This avoids a full redraft if the angle is wrong. ## 4. Determine the next ADR number ```bash ls adrs/[0-9]*.md 2>/dev/null | sort | tail -1 ``` Parse the numeric prefix from the last file (e.g. `0003` from `0003-use-sqlite.md`). Increment by one. If no files exist, start at `0001`. ## 5. Derive the filename Use the decision title in lowercase kebab-case: ``` adrs/<NNNN>-<kebab-title>.md ``` Example: `adrs/0004-store-adrs-in-top-level-folder.md` ## 6. Write the ADR Use this template — keep each section concise (a few sentences to a short paragraph): ```markdown # <NNNN>. <Title> Date: <YYYY-MM-DD> Status: <Accepted | Proposed | Deprecated | Superseded by [NNNN](<link>)> ## Context What situation, constraint, or requirement forced this decision? What was the problem space? ## Decision What was chosen and why? State it directly. ## Alternatives Considered What else was evaluated and why was it not chosen? This is the most important section for future readers — capture each rejected option and the specific reason it lost. ## Consequences What gets easier? What gets harder? What is accepted as a trade-off? ``` **Status values:** - `Accepted` — decision is in effect - `Proposed` — under discussion, not yet finalised - `Deprecated` — no longer relevant but not replaced - `Superseded by [NNNN](NNNN-<title>.md)` — replaced by a later ADR; also update the superseding ADR to note `Supersedes [NNNN]` **What belongs here:** - The reasoning and alternatives considered (with reasons each was rejected) - Constraints that shaped the choice (team size, existing tooling, latency requirements, etc.) - Known trade-offs being accepted **What does not belong here:** - Implementation steps or how-to instructions - Code snippets (unless a tiny illustrative example) - Anything derivable from reading the code ## 7. Present the draft for approval Show the full ADR text and ask for approval or changes before writing. This is a permanent record — it should be accurate. ## 8. Write the file Use the Write tool to create the file with the approved content. ## 9. Report back Tell the user the file path. Offer to stage and commit the file so the decision is captured in git history alongside the code it relates to.