adr

What this skill does

# Create an Architecture Decision Record (ADR)

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

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

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+):

   <!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0019 REQ "qmd-Smart Authoring Skills" -->

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

2. **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.

2b. **Optional call graph embedding** (opt-in, SPEC-0034):

   <!-- Governing: ADR-0033 (cgg call graph integration), SPEC-0034 REQ "Enhanced /sdd:adr" -->

   After the ADR body is fully drafted and before writing to disk, ask the user whether to include a call graph:

   Use `AskUserQuestion` with the prompt:

   > Include a call graph showing where this decision applies in the codebase? (yes / no / skip)

   **Default to "no"** when: the session is non-interactive (piped input), batch/CI mode is detected, or the question times out. In those cases, proceed directly to Step 3 as if the user answered "no" — no error, no deviation from existing behavior.

   **If the user answers "no" or "skip"**: Proceed to Step 3 with an empty `## Architecture Diagram` section (the template placeholder text is omitted; write the section header with no body, or omit the section entirely). No call graph is generated.

   **If the user answers "yes"**:

   1. **Availability check**: Run `which cgg >/dev/null 2>&1`. If cgg is not found, surface the exact unavailability notice from `references/cgg-integration.md` § "Availability Check" and proceed to Step 3 without a call graph.

   2. **Derive the filter**: Extract keywords from the ADR's `## Decision Outcome` section (the chosen option name, key technology names, system names, and any verbs describing the decision). Apply the **From requirement keywords** strategy from `references/cgg-integration.md` § "Filter Derivation Strategy" — lowercase, split on spaces/punctuation, strip stop words, compose a regex alternation. In workspace mode, use the module source directory as `<target-path>` per `references/cgg-integration.md` § "Workspace-Mode Scoping".

   3. **Invoke cgg** using the canonical invocation pattern from `references/cgg-integration.md` § "cgg Invocation Pattern":
      ```bash
      timeout 30 cgg <target-path> --filter "<filter-regex>" --format mermaid 2>/tmp/cgg-stderr-$$.txt
      CGG_EXIT=$?
      CGG_STDERR=$(cat /tmp/cgg-stderr-$$.txt)
      rm -f /tmp/cgg-stderr-$$.txt
      ```

   4. **Handle exit codes** per `references/cgg-integration.md` § "Exit code handling":
      - Exit 0: normalize the Mermaid output per § "Mermaid Output Normalization" (sort nodes, rewrite to `graph TD`, strip hash prefixes, apply 20-node cap, append legend footer).
      - Exit 1 or other non-zero: surface `"Call graph generation failed: "` + stderr; proceed to Step 3 without a call graph.
      - Exit 124 (timeout): surface the exact timeout message from § "Timeout Handling"; proceed to Step 3 without a call graph.

   5. **Handle unsupported-language warnings** per `references/cgg-integration.md` § "Unsupported Language Handling" — emit per-file skip notices; if all files were skipped, fall back to no call graph.

   6. **Embed in the ADR**: On success, replace the `## Architecture Diagram` section with the normalized Mermaid block wrapped per `references/cgg-integration.md` § "Embedding in markdown":
      ```markdown
      <!-- Call graph: <filter used>, generated <YYYY-MM-DD> -->
      ```mermaid
      graph TD
          ...
      ```
      ```
      The caption comment MUST record the exact filter regex used and today's date.

   In every degradation case (cgg missing, timeout, non-zero exit, all files skipped), the skill MUST complete and write the ADR without a call graph. Never surface a hard failure to the user when cgg is the only failing component.

3. **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+):

   <!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 1 Mutation-Aware Updates" -->

   After writing the new ADR file, trigger a narrow re-sync of `{repo}-a