doc-adr
Create an Architecture Decision Record (ADR) - Layer 5 of the SDD flow, documenting one architecture decision with Context-Decision-Consequences. Use after BDD when an architectural choice needs recording. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-adr-autopilot`) drives this skill.
How do I install this agent skill?
npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-adrIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a documentation primitive for creating Architecture Decision Records (ADR). It follows a structured process for recording architectural choices without any malicious code, network access, or sensitive data exposure.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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: EARS, BDD (per the necessary-upstream contract; upstream PRD/BRD lineage is reachable transitively via the @-tag chain). 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 §8 / 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 required upstream artifacts (EARS + BDD) exist and read the spec before writing:
- Template (source of truth):
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml - Layer README:
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md - ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md - Authoring style:
${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
Confirm required upstream artifacts: ls docs/0{3,4}_*/ 2>/dev/null (EARS
and BDD). 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. Upstream PRD/BRD lineage is reachable
transitively via the EARS/BDD @-tag chain.
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 numbered sections + glossary + appendix backmatter)
document_control is Section 1 (status, date, decision-makers, author,
originating_topic → PRD §14, brd_reference, SPEC-Ready score, revision
history). Then:
- Context (problem statement, business driver, constraints, technical context) · 3. Decision (chosen solution, key components, MVP/next-cycle scope) ·
- Alternatives Considered (the selected option plus 2–3 rejected rivals, each with pros/cons; rejected ones name the concrete disqualifying factor — cost and fit optional) · 5. Consequences (positive outcomes, trade-offs/risks with severity, and a cost estimate where the decision commits spend) · 6. Architecture Flow (diagrams + integration points) · 7. Implementation Assessment (phases, rollback, monitoring baseline) · 8. Verification (success criteria, BDD cross-refs) · 9. Traceability · 10. Related Decisions.
Plus a Glossary (glossary: key) and Appendix (appendix: key) as
required backmatter (unnumbered). Section numbers and identifiers come from
ADR-TEMPLATE.yaml's own # Section N: numbering — the template is the
source of truth.
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). Emit a stable 4-hex-char identifier per element, distinct within its section (HASH01); extend to 8 on collision. Do not compute SHA-256 in this prompt — the hash form is the canonicalization TARGET produced by a deterministic tool pass, and byte-exact field extraction is defined for BRD §7 only (Phase 2+ for ADR). Authority:framework/governance/ID_NAMING_STANDARDS.md. 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-NNand@discoverability: ADR-NN (rationale). - Required upstream tags (Layer 5):
@ears @bdd— both required (per the necessary-upstream contract), using each upstream's element-ID form (@ears: EARS.01.03.5e2a,@bdd: BDD.01.03.8f4c). Upstream PRD/BRD lineage is reachable transitively via the EARS/BDD @-tag chain — do not emit@brd:/@prd:on ADR elements. - Removed patterns (do not use):
DEC-XXX,ALT-XXX,CON-XXX, the legacy 3-segmentADR.NN.xxxx, numeric type-code segments, and 3-digitADR-NNN.
Creation Process
- Confirm the topic — one decision, traced to its PRD §14 originating topic and BRD §8 driver.
- Reserve ID — next free
ADR-NN(two digits, expand only as needed:ADR-01,ADR-99,ADR-102). Per-layer independence (CLEANUP-PR-F item 18): pick the next-free number in YOUR layer's index — the upstream's number is NOT your number (doc numbers are per-layer sequential and independent; seeframework/governance/ID_NAMING_STANDARDS.md§Cross-layer cardinality). - Create the nested folder — every ADR lives in
docs/05_ADR/ADR-NN_{slug}/. Monolithic:ADR-NN_{slug}.mdinside it; section-based (>25 KB):ADR-NN.S_{section}.md+ index from${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-00_index.TEMPLATE.md. - Document Control (Section 1) first, then complete §2–§10 plus the glossary and appendix backmatter from the template.
- Evaluate 2–3 alternatives beside the selected option (so
options:carries 3–4 entries) — give every rejected option a rejection reason naming the concrete disqualifying factor.estimated_cost/fitare optional per option; where a fuller survey already exists, cite it inprior_analysisinstead of restating it. State the decision decisively with rationale. - Add the required upstream tags
@ears @bdd; add the@adr: ADR-NNself-tag and any@depends:cross-links. - Update the ADR index
docs/05_ADR/ADR-00_index.mdin the same change. - Validate (below) and commit the ADR and index together.
Validation
This skill is the validator (no runtime code). Apply against ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md and ${CLAUDE_PLUGIN_ROOT}/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 rejected alternatives beside the selected option, each with pros/cons and a concrete disqualifying factor. Cost and fit are optional; an existing survey is cited, not restated.
- Consequences cover positive outcomes and trade-offs (with severity); a cost estimate only where the decision commits spend.
- Element IDs match
ADR.NN.SS.xxxx; document refs use dashADR-NN; no removed patterns. - Required upstream tags
@ears @bddpresent (per necessary-upstream contract);@adr: ADR-NNself-tag. - SPEC-Ready score ≥ 90 if status is Accepted.
- Diagram contract: the Architecture-Flow section carries the decision /
interaction sequence diagram (
@diagram: sequence-*) per${CLAUDE_PLUGIN_ROOT}/framework/governance/DIAGRAM_STANDARDS.md— ADR is the decision bridge, so no C4 level (use../charts-flow/SKILL.md); index updated; no broken links.
| Code | Meaning | Severity |
|---|---|---|
| XDOC-002 | Missing required upstream 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, required upstream tags, and quality gates.
Next Skill
../doc-spec/SKILL.md — the SPEC references this ADR (@adr: ADR-NN) along
with its own required @ears @bdd upstream tags, turning the decision into
component interfaces, data models, and behavior contracts.
Adaptation
Read .aidoc/profile.yaml; honor only this skill's knobs
(section_toggles, glossary). Ignore unknown keys; absent a profile, use
framework defaults. Authority:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.
Related Resources
- Template / authoring rules:
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml - Layer README:
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md - Index template:
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-00_index.TEMPLATE.md - ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/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 | @ears @bdd (per necessary-upstream contract) |
| 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 beside the selected option |
| Next | doc-spec |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vladm3105/aidoc-flow-framework/doc-adr">View doc-adr on skillZs</a>