doc-adr

doc-adr

Purpose

Create an Architecture Decision Record (ADR) — Layer 5 of the SDD flow. An ADR records one architecture decision using the Context-Decision- Consequences pattern: why the decision is needed, what was chosen, the alternatives weighed, and the consequences accepted.

Layer: 5 — the decision bridge between Container (PRD) and Component (SPEC); ADR is not itself a C4 level. Upstream: BRD → PRD → EARS → BDD. Downstream: SPEC → TDD → IPLAN → Code.

Each ADR addresses exactly one decision. A new architectural choice gets a new ADR (ADR-02, ADR-03, …) rather than expanding an existing one; relate them with @depends: ADR-NN.

When to Use

Use doc-adr when:

• An architectural topic from BRD §7.2 / PRD §14 needs a recorded decision.
• Choosing a technology, pattern, or integration approach with alternatives.
• Capturing rationale and consequences for a long-lived architectural choice.

For end-to-end generation from an upstream artifact or a prompt, use ../doc-adr-autopilot/SKILL.md. To plan the set of ADRs a project needs, see ../adr-roadmap/SKILL.md.

Prerequisites

ADR is Layer 5, so verify the upstream chain exists and read the spec before writing:

1. Template (source of truth): framework/layers/05_ADR/ADR-TEMPLATE.yaml
2. Layer README: framework/layers/05_ADR/README.md
3. ID & tag standards: framework/governance/ID_NAMING_STANDARDS.md

Confirm upstream artifacts: ls docs/0{1,2,3,4}_*/ 2>/dev/null. Reference only documents that already exist; never invent placeholders like ADR-XXX or cite SPEC numbers that do not yet exist. Confirm no ID collision: ls docs/05_ADR/ 2>/dev/null.

Layer Guidance

Status lifecycle (ADR is different)

ADR uses Proposed → Accepted → Deprecated → Superseded — not Draft/In Review/Approved. The status tracks the SPEC-Ready score:

Status	SPEC-Ready	Meaning
Proposed	70–89%	Decision under evaluation
Accepted	≥90%	Approved, ready for SPEC
Deprecated	—	No longer relevant (kept for history)
Superseded	—	Replaced by a newer ADR (link it)

Required structure (10 sections)

## Document Control comes first (status, date, decision-makers, author, originating_topic → PRD §14, brd_reference, SPEC-Ready score, revision history). Then:

1. Context (problem statement, business driver, constraints, technical context) · 2. Decision (chosen solution, key components, MVP/next-cycle scope) ·
2. Alternatives Considered (2–3 options, each with pros/cons, cost, fit; rejected options carry a rejection reason) · 4. Consequences (positive outcomes, trade-offs/risks with severity, cost estimate) · 5. Architecture Flow (diagrams + integration points) · 6. Implementation Assessment (phases, rollback, monitoring baseline) · 7. Verification (success criteria, BDD cross-refs) · 8. Traceability · 9. Related Decisions · 10. Glossary.

See ADR-TEMPLATE.yaml for per-section content and authoring _antipatterns.

Element IDs and tags

• Element IDs (inside the ADR): ADR.{doc_id}.{section_id}.{hash} (e.g. ADR.01.03.e5b1; hash = first 4 hex of SHA256 of "{doc_id}:{section_id}:{title}:{description}", extend to 8 on collision). There are no numeric type-codes — an element's kind is given by its section.
• ADR is a DOCUMENT-level artifact. It is referenced in dash form ADR-NN, never as a dotted element ID. The self-tag is @adr: ADR-NN (e.g. @adr: ADR-033); cross-links use @depends: ADR-NN and @discoverability: ADR-NN (rationale).
• Cumulative upstream tags (Layer 5): @brd @prd @ears @bdd — all four required, using each upstream's element-ID form (@brd: BRD.01.08.0a13, @prd: PRD.01.14.0702, @ears: EARS.01.03.5e2a, @bdd: BDD.01.03.8f4c).
• Removed patterns (do not use): DEC-XXX, ALT-XXX, CON-XXX, the legacy 3-segment ADR.NN.xxxx, numeric type-code segments, and 3-digit ADR-NNN.

Creation Process

1. Confirm the topic — one decision, traced to its PRD §14 originating topic and BRD §7.2 driver.
2. Reserve ID — next free ADR-NN (two digits, expand only as needed: ADR-01, ADR-99, ADR-102).
3. Create the nested folder — every ADR lives in docs/05_ADR/ADR-NN_{slug}/. Monolithic: ADR-NN_{slug}.md inside it; section-based (>25 KB): ADR-NN.S_{section}.md + index from framework/layers/05_ADR/ADR-00_index.TEMPLATE.md.
4. Document Control first, then complete all 10 sections from the template.
5. Evaluate 2–3 alternatives with cost and fit; give every rejected option a rejection reason. State the decision decisively with rationale.
6. Add cumulative tags @brd @prd @ears @bdd; add the @adr: ADR-NN self-tag and any @depends: cross-links.
7. Update the ADR index docs/05_ADR/ADR-00_index.md in the same change.
8. Validate (below) and commit the ADR and index together.

Validation

The framework ships no runtime code — this skill is the validator. Apply the checklist against framework/layers/05_ADR/README.md and framework/governance/ID_NAMING_STANDARDS.md.

• Document Control is the first section; status is one of Proposed/Accepted/Deprecated/Superseded.
• All 10 sections present and non-empty; exactly one decision.
• 2–3 alternatives, each with pros/cons + cost; rejected ones have a reason.
• Consequences cover positive outcomes, trade-offs (with severity), cost.
• Element IDs match ADR.NN.SS.xxxx; document refs use dash ADR-NN; no removed patterns.
• Cumulative tags @brd @prd @ears @bdd present; @adr: ADR-NN self-tag.
• SPEC-Ready score ≥ 90 if status is Accepted.
• Diagram contract: architecture-flow diagram present (use ../charts-flow/SKILL.md); index updated; no broken links.

Code	Meaning	Severity
XDOC-002	Missing cumulative tag	error
XDOC-006	Tag format invalid	error
XDOC-008	Broken internal link	error
XDOC-009	Missing traceability section	error

Quality gate (blocking): SPEC-Ready score ≥ 90/100 before moving on. If issues are found, fix and re-check; if unfixable, log for manual review.

ADR-REF documents (ADR-REF-NN_{slug}.md, via ../doc-ref/SKILL.md) are free-format reference targets — exempt from ready-scores, cumulative tags, and quality gates.

Next Skill

../doc-spec/SKILL.md — the SPEC references this ADR (@adr: ADR-NN), turns the decision into component interfaces, data models, and behavior contracts, and inherits the cumulative tag chain.

Adaptation

Before applying defaults, read the project adaptation profile (.aidoc/profile.yaml). Honor only this skill's declared knobs: section_toggles (include or omit template-declared optional sections) and glossary (substitute preferred terms in generated prose). Ignore any unknown or out-of-surface key; absent a profile, use framework defaults. Authority: framework/governance/ADAPTATION.md.

Related Resources

• Template / authoring rules: framework/layers/05_ADR/ADR-TEMPLATE.yaml
• Layer README: framework/layers/05_ADR/README.md
• Index template: framework/layers/05_ADR/ADR-00_index.TEMPLATE.md
• ID & tag standards: framework/governance/ID_NAMING_STANDARDS.md
• Quality gate: ../doc-adr-audit/SKILL.md · Fixes: ../doc-adr-fixer/SKILL.md
• Generation pipeline: ../doc-adr-autopilot/SKILL.md
• Decision planning: ../adr-roadmap/SKILL.md

Quick Reference

Purpose	Record one architecture decision (Context-Decision-Consequences)
Layer	5 (decision bridge: PRD → SPEC)
Upstream tags	@brd @prd @ears @bdd (all four required)
Self-reference	dash form @adr: ADR-NN (document-level)
Element IDs	ADR.NN.SS.xxxx (internal elements only)
Status	Proposed → Accepted → Deprecated → Superseded
Must include	Document Control (first), 10 sections, 2–3 alternatives
Next	doc-spec