adr

name

adr

description

Help the user author a well-specified Architecture Decision Record (ADR) — a single, well-scoped decision with context, consequences, and verifiable acceptance criteria. Use when the user wants to write / draft / scope an ADR, record an architecture or technical decision, turn a rough idea or issue into a decision record, or prepare a spec to feed the `orchestrate` planning skill. Discovers the repo's existing ADR convention and ledger, interviews only where the request is vague, grounds lightly in real code, and pre-validates the result against the same rubric `orchestrate`'s Phase 0 gate scores — so a code-change ADR hands off cleanly. Not for general documentation, multi-decision design docs, or writing the implementation plan itself (that is `orchestrate`'s job).

adr — author a well-specified Architecture Decision Record

Turn a decision the user is making into a well-formed ADR that, when it's a code change, clears orchestrate's Phase 0 gate on the first try and gives its planning stages what they need. You are an interactive conductor: you discover the repo's convention, interview the user only where they're vague, ground lightly in real code, and emit one convention-correct ADR file. Full rationale is in dev/adr/DESIGN.md and dev/adr/ADR_ANALYSIS.md.

The value is elicitation — asking the questions the gate would ask, before, so the answer becomes the ADR instead of a rejection. Don't interrogate what the user already stated clearly.

Reference files

• references/adr-template.md — the emitted shape (Nygard core + code-change sections). It carries no rubric text: the section↔dimension mapping and each dimension's pass condition are loaded from $RUBRIC (orchestrate/references/spec-quality.md) at runtime, never embedded here.
• references/verification-modes.md — the 5 acceptance-criteria modes + the non-negotiable code-change rule.
• references/reformulation-patterns.md — generic vague→verifiable rewrites.
• scripts/discover-adr-convention.sh — read-only repo/ledger detection (Phase 0).
• dev/adr/tests/discover-adr-convention.sh — regression guard for that parser (supersession direction, Related ADRs:, prose-vs-metadata excerpts, numbering, CodeGraph root scoping). Run it before shipping any change to the discovery script: bash dev/adr/tests/discover-adr-convention.sh.

Preflight — the shared rubric (peer dependency on orchestrate)

The definition of "well-specified" lives once, in the sibling orchestrate skill. Resolve it and read it — never keep a copy here.

ORCH="$(dirname "$SKILL_DIR")/orchestrate"          # sibling skill (…/skills/orchestrate)
RUBRIC="$ORCH/references/spec-quality.md"
[ -f "$RUBRIC" ] && echo "rubric OK" || echo "DEGRADED: orchestrate skill not found"

• Present: read the ```json block in $RUBRIC — that's the authoritative list of Phase-0 dimensions (id · label · pass_condition · elicitation_hint), used to drive Phase 2 and Phase 4.
• Absent (degraded mode): still author a well-formed ADR (the Nygard core is self-contained), but warn you can't guarantee orchestrate-readiness (no rubric to self-check against) and don't promise a code-change handoff. Never fall back to an embedded rubric copy.

---

Phase 0 — Discovery (read-only, before any questions)

Run bash "$SKILL_DIR/scripts/discover-adr-convention.sh" "$REPO_ROOT" and parse its JSON: { adr_dir, index_file, next_number, number_format, status_vocab, template_style, has_codegraph, existing_adrs[] }. Everything discovered overrides defaults; the defaults (docs/adr/NNN-<slug>.md, status: proposed, Nygard template) apply only when adr_dir is null. Never reject an ADR for deviating from a default convention.

Phase 1 — Intake & classify

• Read what the user already gave you (a sentence, paragraph, rough draft, linked issue). Adaptive: lots supplied → critique-and-fill; little supplied → interview.
• Ledger check (ADR-as-DRY): scan existing_adrs[] for overlap with this decision; read the full text of the likely-overlap candidates (not just titles). Ask the user whether this is new / amends / supersedes an existing ADR → set Related ADRs / Supersedes metadata. Don't restate what another ADR already decides — link or supersede.
• No-ledger / no-convention branch: if adr_dir is null, do not silently create anything. Confirm the ADR file path with the user (offer the default), and by default write only that single file. Scaffold an index/ledger directory only after explicit confirmation.
• Classify handoff suitability — this gates Phase 5:
  • code-change — the decision entails implementation; the code-change sections + rubric apply.
  • docs-only / no-op — a policy/process/pure-architecture decision with no immediate code; author the core ADR, skip implementation-style criteria, and offer no orchestrate handoff.
  • not-ready — the decision itself is unsettled; surface what's undecided rather than inventing a spec.

Phase 2 — Elicitation (only for weak/missing pieces)

Always elicit the invariant ADR core: Context · Decision · Consequences (one decision — if there are several, split into separate ADRs). For a code-change ADR, also cover the Phase-0 dimensions: read each dimension from $RUBRIC's JSON and, for any that's weak/absent, ask its elicitation_hint — but skip what the user already stated clearly.

• Push vague → verifiable (references/reformulation-patterns.md). Give every acceptance criterion a verification mode (automated-test | metric/SLO | manual-review | migration-check | policy-signoff). Forward-looking extra (beyond Phase 0 — see verification-modes.md): a code-change ADR needs ≥1 automated-test-shaped criterion. If the user gives none, propose one for confirmation; if they reject it and none is possible, reclassify not-ready or deliver without a code-change handoff — never hand a testless code-change ADR to orchestrate.
• Thin grounding — highest-fidelity source first. When discovery.has_codegraph is true, use codegraph explore / the CodeGraph MCP first to find the anchor set (symbols + call paths); fall back to rg/glob/read only when there's no .codegraph/ or CodeGraph fails. Capture likely affected files/symbols + current constraints as anchors — a capped set (≤ 7); over the cap, keep the highest-signal and note the elision. Never produce ordered steps or a workstream/lane decomposition — that is orchestrate's job.

Phase 3 — Draft

Emit the ADR from references/adr-template.md in the discovered convention (path, number from next_number/number_format, status from status_vocab, template style), including the ledger metadata. Keep it an ADR — one decision, short (≈ a page). Write to the path resolved in Phase 1 (the discovered convention's path, or the user-confirmed path when none existed — never a silent default). That path is the future spec_path.

Phase 4 — Self-check (code-change only; requires orchestrate present)

Read $RUBRIC's JSON and score the draft against each dimension's pass_condition — exactly as orchestrate's Phase 0 will (same source, no drift). Separately confirm the forward-looking extras (≥1 automated-test-shaped criterion; anchors present), labelled beyond Phase 0. Surface any residual gap and loop back to Phase 2 rather than shipping a spec that would bounce. Phase 0 remains authoritative — this is a courtesy pre-check, not a replacement.

Phase 5 — Handoff

• code-change: present the ADR + its path, and offer to hand off to the orchestrate skill (its conductor) with the ADR text + spec_path — let it bind run provenance and gate. Do not call orchestrate.workflow.js directly (you'd skip the provenance binding and strip the plan's audit anchor). Invoking is the user's call.
• docs-only / no-op: deliver the ADR; offer no orchestrate handoff. Don't claim it "would no-op" — orchestrate runs its quality gate before the step that can return route:"noop", so a non-code ADR would be blocked by the gate first. Non-code ADRs are simply authored and not handed off.
• not-ready: deliver what exists and list the specific undecided points.

Anti-goals

• Not a design doc — one decision per ADR; split multi-decision requests.
• Not a planner — anchors only; no ordered steps or lane decomposition.
• Not a rubric fork — read the canonical dimensions from $RUBRIC; embed none.
• Not a form — friction only where the user was vague.
• Not silent on non-code decisions — author them properly and don't hand them off.