Create an Architecture Decision Record (ADR)

Create an Architecture Decision Record (ADR)

You are creating a new ADR using the MADR (Markdown Architectural Decision Records) format.

Process

0. Resolve artifact paths: Follow the Artifact Path Resolution pattern from references/shared-patterns.md to determine the ADR directory. If $ARGUMENTS contains --module <name>, resolve paths relative to that module. The resolved ADR directory is referred to as {adr-dir} below.

1. Determine the next ADR number: Scan {adr-dir} for existing ADR-XXXX-*.md files and increment to the next number. Start at ADR-0001 if none exist. Create {adr-dir} if it does not exist. If $ARGUMENTS is empty (ignoring flags like --review and --module), use AskUserQuestion to ask the user what decision they want to document.

1a. qmd-aware edge pre-search (v5.0.0+):

Before drafting, qmd-search the existing ADR corpus to find related prior decisions whose IDs SHOULD appear in the new ADR's frontmatter as supersedes, extends, or related edges (per ADR-0023 / SPEC-0018 frontmatter DAG).

1. Construct a hybrid query per references/qmd-helpers.md § "Hybrid Retrieval":

   • lex: the user's description from $ARGUMENTS (key technologies, named systems, decision verbs)
   • vec: a one-sentence framing of the decision the new ADR will make
   • intent: "/sdd:adr — find related prior ADRs to suggest as frontmatter edges"
   • collections: ["{repo}-adrs"] (or per-module variant in workspace mode per qmd-helpers.md § "This-Repo Collection Identification")
   • limit: 6, minScore: 0.3

2. For each result above the threshold, classify the candidate edge:

   • supersedes: the new ADR's description includes "replace", "deprecate", "stop using", "switch from X to Y" and the matched ADR documents X
   • extends: the new ADR builds on the matched ADR's foundation without replacing it
   • related: weak association — same domain, named technology, or shared concern

3. Surface the candidate edges to the user via AskUserQuestion BEFORE writing the file. Show each candidate with the matched ADR's ID, title, and proposed edge classification. Options for each candidate: "Include as {edge}", "Include as related instead", "Skip". The user can override the classification if the agent's guess is wrong.

4. If qmd returns zero results above the threshold, proceed without surfacing edge suggestions and emit a one-line note: "No related ADRs found — drafting from scratch."

5. On qmd unreachable / timeout per qmd-helpers.md § "Error Handling", surface the error and stop. Per ADR-0024, fallback paths were eliminated in v5; the failure mode is "fix qmd, retry."

6. Choose drafting mode: Check if $ARGUMENTS contains --review.

   Default (no --review): Single-agent mode. Research the codebase (read relevant files, understand the current architecture), draft the ADR directly, self-review against the architect's checklist in the Rules section, then write the file.

   With --review: Team review mode.

   • Tell the user: "Creating a drafting team to write and review the ADR. This takes a minute or two."
   • Create a Claude Team with TeamCreate to draft and review the ADR:
     • Spawn a drafter agent (general-purpose) to write the ADR based on the user's description: $ARGUMENTS
     • Spawn an architect agent (general-purpose) to review the drafter's output for completeness, accuracy, and adherence to MADR format
     • The architect MUST review and approve the ADR before it is finalized
     • The drafter should research the codebase (read relevant files, understand the current architecture) before writing
     • If TeamCreate fails, fall back to single-agent mode: draft the ADR directly, then self-review against the architect's checklist in the Rules section before writing.

7. Write the ADR to {adr-dir}/ADR-XXXX-short-title.md. Include the user-confirmed frontmatter edges from Step 1a in the YAML frontmatter (per the canonical edge schema in references/shared-patterns.md § "Graph Edge Resolution").

3a. Tier 1 mutation update (v5.0.0+):

After writing the new ADR file, trigger a narrow re-sync of {repo}-adrs so the qmd index reflects the new artifact. Use the canonical update pattern from references/qmd-helpers.md § "Update Patterns" → "Narrow update". The update is synchronous and silent on success. On failure, append a one-line warning to the report ("Index refresh failed for {repo}-adrs — run /sdd:index update manually") but report the ADR creation itself as successful.

4. Clean up the team when done (if --review was used).

5. Summarize what happened (files created, decision documented, review outcome).

6. Suggest next steps: After summarizing, tell the user:

   • "To formalize requirements from this decision, run: /sdd:spec {suggested capability name}"
   • "The spec skill can also break requirements into trackable issues (Beads, GitHub, or Gitea) for sprint planning."

7. CLAUDE.md integration: Check if this is the first ADR (i.e., {adr-dir} was just created or contains only this new file). If so:

   • Check if a CLAUDE.md exists at the module root (or project root for single-module projects)
   • If it exists, check if it already references the ADR directory
   • If no reference exists, ask the user: "I can add an Architecture Context section to your CLAUDE.md so future sessions know about your decisions. Shall I?"
   • If the user says yes, append an ## Architecture Context section with - Architecture Decision Records are in {adr-dir}
   • If CLAUDE.md doesn't exist, suggest creating one

Team Handoff Protocol (only for --review mode)

Follow the standard team handoff protocol from the plugin's references/shared-patterns.md. The drafter writes the ADR; the architect reviews against the Rules checklist below.

MADR Template

---
status: proposed
date: {YYYY-MM-DD}
decision-makers: {list}
# Optional graph edges (per ADR-0023 / SPEC-0018). All fields are lists of artifact IDs.
# Only include the fields that apply; omit unused fields entirely. Forward-only:
# inverse edges (superseded-by, governed-by, implemented-by, etc.) are derived by
# /sdd:graph at build time and MUST NOT be authored.
# supersedes: [ADR-XXXX]              # hard replacement; target moves to status: superseded
# extends: [ADR-XXXX]                 # builds on without replacing
# enables: [ADR-XXXX]                 # this decision unblocks another
# governs: [SPEC-XXXX]                # specs this decision governs
# related: [ADR-XXXX]                 # weak association, no semantic claim
---

# ADR-XXXX: {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement in 2-3 sentences. Articulate the problem as a question if possible.}

## Decision Drivers

* {driver 1, e.g., a force, facing concern}
* {driver 2}

## Considered Options

* {option 1}
* {option 2}
* {option 3}

## Decision Outcome

Chosen option: "{option}", because {justification}.

### Consequences

* Good, because {positive consequence}
* Bad, because {negative consequence}

### Confirmation

{How will compliance/implementation be confirmed?}

## Pros and Cons of the Options

### {Option 1}

{Description or pointer to more information.}

* Good, because {argument a}
* Good, because {argument b}
* Neutral, because {argument c}
* Bad, because {argument d}

### {Option 2}

{Description or pointer to more information.}

* Good, because {argument a}
* Bad, because {argument b}

## Architecture Diagram

```mermaid
{Mermaid diagram illustrating the architecture, decision flow, or component relationships.
Use flowchart, sequence, or C4 diagrams as appropriate.}

More Information

{Additional context, links to related ADRs, references.}

## Rules

- ADR numbers MUST be sequential and zero-padded to 4 digits: ADR-0001, ADR-0002, etc.
- MUST include at least 2 considered options with substantive pros and cons for each
- Status starts as `proposed` -- the user decides when to mark `accepted`
- Self-review (default) or architect review (`--review`) MUST check for:
  - Completeness of all required sections (Context, Options, Outcome, Pros/Cons)
  - Realistic and balanced pros/cons (not just cheerleading the chosen option)
  - Clear decision rationale that explains "why this over alternatives"
  - Correct MADR structure and frontmatter
- Keep the title short and descriptive
- Focus on the "why" -- what problem does this solve and why this solution?
- Reference existing ADRs if this supersedes or relates to them
- Every ADR SHOULD include at least one Mermaid diagram illustrating the architecture or decision flow. Use flowchart, sequence, or C4 diagrams as appropriate.
- **v5.0.0+**: MUST run qmd-aware edge pre-search per Step 1a — surface candidate `supersedes`/`extends`/`related` edges to the user via AskUserQuestion before drafting. The user's confirmed edges land in the new ADR's frontmatter (Governing: ADR-0024, SPEC-0019 REQ "qmd-Smart Authoring Skills")
- **v5.0.0+**: MUST trigger Tier 1 `{repo}-adrs` re-sync after writing the new file per Step 3a — best-effort, silent on success, one-line warning on failure (Governing: ADR-0026, SPEC-0019 REQ "Tier 1 Mutation-Aware Updates")
- **v5.0.0+**: On qmd unreachable / timeout during the edge pre-search, MUST surface the error and stop — never fall back to "draft without edge suggestions" (per ADR-0024)

## Graph Edge Frontmatter (per ADR-0023 / SPEC-0018)

<!-- Governing: ADR-0023 (Frontmatter DAG and /sdd:graph Skill), SPEC-0018 REQ "Frontmatter Edge Schema" -->

ADRs MAY declare relationships to other artifacts via optional frontmatter fields. All edge fields MUST be lists of artifact IDs (e.g., `[ADR-0008, ADR-0009]`). All edge fields are OPTIONAL — an ADR with no declared edges is valid.

| Field | Meaning | Example |
|-------|---------|---------|
| `supersedes` | Hard replacement — the referenced ADR moves to status `superseded` | `supersedes: [ADR-0003]` |
| `extends` | Builds on without replacing | `extends: [ADR-0008, ADR-0009]` |
| `enables` | Unblocks a downstream decision | `enables: [ADR-0016]` |
| `governs` | Names specs this decision governs | `governs: [SPEC-0007, SPEC-0010]` |
| `related` | Weak association, no semantic claim | `related: [ADR-0010]` |

**Forward-only convention.** Only forward edges are authored. Reverse edges (`superseded-by`, `governed-by`, `enabled-by`, `extended-by`) are derived by `/sdd:graph` at build time and MUST NOT appear in frontmatter — the graph builder will reject them with a warning. See `references/shared-patterns.md` § "Graph Edge Resolution" for the full forward→inverse derivation table.

**Cross-module edges (workspace mode).** When referencing artifacts in another module, use the quoted `[module]/ID` syntax: `governs: ["[api]/SPEC-0001"]`. The unquoted form `[[api]/SPEC-0001]` parses as YAML nested lists and will be rejected.

**When to add edges.** Add edges as the relationship becomes structurally meaningful — typically at the same time you would have written "Related: ADR-XXXX" in `## More Information`. Backfilling existing ADRs is supported via `/sdd:graph backfill`, which proposes edges parsed from prose for per-file review.