doc-adr

Purpose

Create Architecture Decision Records (ADR) - Layer 5 artifact in the SDD workflow that documents architectural decisions with rationale, alternatives, and consequences.

Layer: 5

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4)

Downstream Artifacts: SYS (Layer 6), REQ (Layer 7), Code (Execution Layer)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

List existing upstream artifacts:

ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ 2>/dev/null

Reference only existing documents in traceability tags

Use null only when upstream artifact type genuinely doesn't exist

NEVER use placeholders like BRD-XXX or TBD

Do NOT create missing upstream artifacts - skip functionality instead

Before creating ADR, read:

• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

• Technology Stack: docs/05_ADR/ADR-00_technology_stack.md (approved technologies)

• Upstream BRD, PRD: Read Architecture Decision Requirements sections

• Template: ai_dev_ssd_flow/05_ADR/ADR-MVP-TEMPLATE.md

• Creation Rules: ai_dev_ssd_flow/05_ADR/ADR_MVP_CREATION_RULES.md

• Validation Rules: ai_dev_ssd_flow/05_ADR/ADR_MVP_VALIDATION_RULES.md

• Quality Gate Validation: ai_dev_ssd_flow/05_ADR/ADR_MVP_QUALITY_GATE_VALIDATION.md

When to Use This Skill

Use doc-adr when:

• Have identified architectural topics in BRD/PRD Architecture Decision Requirements sections

• Need to document technology choices with rationale

• Evaluating alternatives for architectural patterns

• Making decisions with long-term impact

• You are at Layer 5 of the SDD workflow

ADR Document Categories

Category Filename Pattern Validation Level Description

Standard ADR ADR-NN_{decision_topic}.md

Full (7 checks) Architecture decision records

ADR-REF ADR-REF-NN_{slug}.md

Reduced (4 checks) Supplementary reference documents

Reserved ID Exemption (ADR-00_*)

Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.

Pattern: ADR-00_*.md

Document Types: Index, Traceability matrix, Glossaries, Registries, Checklists

Validation Behavior: Skip all checks when filename matches ADR-00_* pattern.

ADR-Specific Guidance

1. ADR Structure (11 Sections Total)

MVP Template: See ai_dev_ssd_flow/05_ADR/ADR-MVP-TEMPLATE.md for complete structure.

Section Purpose

1 Document Control Metadata with SYS-Ready Score

2 Context Problem Statement, Technical Context

3 Decision Chosen Solution, Key Components, Approach

4 Alternatives Considered Options with pros/cons

5 Consequences Positive/Negative Outcomes, Costs

6 Architecture Flow Mermaid diagrams, Integration Points

7 Implementation Assessment Phases, Rollback, Monitoring

8 Verification Success Criteria, BDD Scenarios

9 Traceability Upstream/Downstream, Tags, Cross-Links

10 Related Decisions Dependencies, Supersessions

11 MVP Lifecycle Iteration guidance

2. ADR Lifecycle States

Proposed: Decision under consideration

• Still evaluating alternatives

• Seeking stakeholder feedback

• Not yet implemented

Accepted: Decision approved and active

• Chosen as the path forward

• Implementation can proceed

• Should be followed by all

Deprecated: Decision no longer recommended

• Better alternative found

• Context changed

• Not deleted (historical record)

Superseded by ADR-XXX: Replaced by newer decision

• Links to replacing ADR

• Explains why replaced

• Maintains audit trail

3. SYS-Ready Scoring System

Purpose: Measures ADR maturity and readiness for progression to System Requirements (SYS) phase.

Format in Document Control:

| SYS-Ready Score | ✅ 95% (Target: ≥90%) |

Status and SYS-Ready Score Mapping:

SYS-Ready Score Required Status

≥90% Accepted

70-89% Proposed

<70% Draft

Scoring Criteria:

• Decision Completeness (30%): Context/Decision/Consequences/Alternatives process

• Architecture Clarity (35%): Mermaid diagrams (REQUIRED - no text-based diagrams), component responsibilities, cross-cutting concerns

• Implementation Readiness (20%): Complexity assessment, dependencies, rollback strategies

• Verification Approach (15%): Testing strategy, success metrics, operational readiness

Quality Gate: Score <90% blocks SYS artifact creation.

4. Element ID Format (MANDATORY)

Pattern: ADR.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

Element Type Code Example

Decision 10 ADR.02.10.01

Alternative 12 ADR.02.12.01

Consequence 13 ADR.02.13.01

REMOVED PATTERNS - Do NOT use legacy formats:

• ❌ DEC-XXX → Use ADR.NN.10.SS

• ❌ ALT-XXX → Use ADR.NN.12.SS

• ❌ CON-XXX → Use ADR.NN.13.SS

Reference: ID_NAMING_STANDARDS.md

5. Threshold Management

Dual Role: ADR documents both reference and define thresholds.

Reference platform-wide thresholds from PRD threshold registry:

performance:

• "@threshold: PRD.NN.perf.api.p95_latency" sla:
• "@threshold: PRD.NN.sla.uptime.target"

Define architecture-specific thresholds unique to this decision:

circuit_breaker:

• "@threshold: ADR.NN.circuit.failure_threshold"
• "@threshold: ADR.NN.circuit.recovery_timeout" retry:
• "@threshold: ADR.NN.retry.max_attempts" caching:
• "@threshold: ADR.NN.cache.ttl_seconds"

6. File Size Limits

• Target: 800 lines per file

• Maximum: 1200 lines per file (absolute)

• If document approaches/exceeds limits, split into section files

Tag Format Convention (By Design)

Notation Format Artifacts Purpose

Dash TYPE-NN ADR, SPEC, CTR Technical artifacts - references to files/documents

Dot TYPE.NN.TT.SS BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS Hierarchical artifacts - references to elements inside documents

Key Distinction:

• @adr: ADR-033 → Points to the document ADR-033_risk_limit_enforcement.md

• @brd: BRD.17.01.30 → Points to element 01.30 inside document BRD-017.md

Cumulative Tagging Requirements

Layer 5 (ADR): Must include tags from Layers 1-4 (BRD, PRD, EARS, BDD)

Tag Count: 4 tags (@brd, @prd, @ears, @bdd)

Format:

Traceability

Required Tags (Cumulative Tagging Hierarchy - Layer 5):

@brd: BRD.01.01.30 @prd: PRD.01.07.02 @ears: EARS.01.25.01 @bdd: BDD.01.14.01

Upstream Sources:

• BRD-01 - Architecture Decision Requirements

• PRD-01 - Product requirements

• EARS-01 - Formal requirements (EARS type code: 25)

• BDD-01 - Test scenarios (BDD scenario type code: 14)

Upstream/Downstream Artifacts

Upstream Sources:

• BRD (Layer 1) - Architecture Decision Requirements section

• PRD (Layer 2) - Architecture Decision Requirements section

• EARS (Layer 3) - Formal requirements constraints

• BDD (Layer 4) - Test scenarios validating decision

Downstream Artifacts:

• SYS (Layer 6) - System requirements implementing decision

• REQ (Layer 7) - Atomic requirements following decision

• Code (Execution Layer) - Implementation per decision

Upstream-Only Traceability Policy:

The ADR traceability matrix tracks ADRs and their upstream sources (BRD, PRD, EARS, BDD) only. Downstream documents (SYS, REQ, SPEC) track their own upstream references to ADRs—the ADR matrix does NOT maintain downstream links.

Same-Type Document Relationships (conditional):

• @related-adr: ADR-NN

• ADRs sharing architectural context

• @depends-adr: ADR-NN

• ADR that must be decided first

Cross-Linking Tags (AI-Friendly)

Purpose: Establish lightweight, machine-readable hints for AI discoverability and dependency tracing across ADR documents without blocking validation.

Tags Supported:

• @depends: ADR-NN — Hard prerequisite; this ADR cannot proceed without the referenced ADR

• @discoverability: ADR-NN (short rationale) — Related document for AI search and ranking (informational)

ID Format: Document-level IDs follow {DOC_TYPE}-NN per ID_NAMING_STANDARDS.md (e.g., ADR-01 , ADR-02 ).

Placement: Add tags to the Traceability section or inline with decision descriptions.

Example:

@depends: ADR-01 (Technology Stack) @discoverability: ADR-02 (Database Strategy - related architecture decision)

Validator Behavior: Cross-linking tags are recognized and reported as info-level findings (non-blocking). They enable AI/LLM tools to infer relationships and improve search ranking without affecting document approval.

Optional for MVP: Cross-linking tags are optional in MVP templates and are not required for ADR approval; they are purely informational.

Creation Process

Step 1: Identify Decision Topic

From BRD/PRD Architecture Decision Requirements sections, identify topic needing decision.

Step 2: Read Technology Stack

Check docs/05_ADR/ADR-00_technology_stack.md for approved technologies.

Step 3: Reserve ID Number

Check docs/05_ADR/ for next available ID number (e.g., ADR-01, ADR-33).

ID Numbering Convention: Start with 2 digits and expand only as needed.

• ✅ Correct: ADR-01, ADR-99, ADR-102

• ❌ Incorrect: ADR-001, ADR-033 (extra leading zero not required)

Special IDs:

• ADR-000: Reserved for Technology Stack reference

• ADR-01 onwards: Regular decision records

Step 4: Create ADR Folder and Files

Folder structure (DEFAULT - nested folder per document):

• Create folder: docs/05_ADR/ADR-NN_{slug}/ (folder slug MUST match index file slug)

• Create index file: docs/05_ADR/ADR-NN_{slug}/ADR-NN.0_{slug}_index.md

• Create section files: docs/05_ADR/ADR-NN_{slug}/ADR-NN.S_{section_type}.md

Example (Section-Based Pattern - DEFAULT):

docs/05_ADR/ADR-033_database_selection/ ├── ADR-033.0_database_selection_index.md ├── ADR-033.1_context.md ├── ADR-033.2_decision.md └── ADR-033.3_consequences.md

Monolithic Option (for small documents ≤25KB): docs/05_ADR/ADR-NN_{slug}/ADR-NN_{slug}.md (still in nested folder)

Step 5: Fill Document Control Section

Complete all required metadata fields and initialize Document Revision History table.

Required Fields (7 mandatory):

• Project Name, Document Version, Date, Document Owner, Prepared By, Status, SYS-Ready Score

Step 6: Document Context (Section 4)

Context Section: Explain the problem and factors:

• What issue are we addressing?

• What constraints exist?

• What requirements drive this decision?

• Reference upstream BRD/PRD sections

Section 4.1 Problem Statement includes inherited content:

• Business Driver (from BRD §7.2)

• Business Constraints (from BRD §7.2)

• Technical Options Evaluated (from PRD §18)

• Evaluation Criteria (from PRD §18)

Step 7: State Decision (Section 5)

Decision Section: Clear, concise statement:

• What are we choosing to do?

• How will it be implemented?

• Reference technology stack (ADR-000) if applicable

Step 8: Analyze Consequences (Section 7)

Consequences Section:

• Positive: Benefits and advantages

• Negative: Drawbacks and limitations

• Risks: Potential issues and mitigations

Step 9: Document Alternatives (Section 12)

Alternatives Considered: For each alternative:

• Name and description

• Pros and cons

• Why rejected

• Fit Score (Poor/Good/Better)

Step 10: Define Verification (Section 11)

Verification Section: How to validate decision:

• BDD scenarios that test it

• Success metrics

• Performance benchmarks

Step 11: Add Relations (Section 14)

Related Decisions Section:

• Supersedes: Which ADR this replaces

• Related to: Connected ADRs

• Influences: Which SYS/REQ depend on this

Step 12: Add Cumulative Tags (Section 16.6)

Include @brd, @prd, @ears, @bdd tags (Layers 1-4).

Step 13: Create/Update Traceability Matrix

MANDATORY: Update docs/05_ADR/ADR-00_TRACEABILITY_MATRIX.md

• Add ADR entry with upstream sources only (BRD, PRD, EARS, BDD)

• Do NOT add downstream links (SYS, REQ track their own references to ADRs)

Step 14: Commit Changes

Commit ADR and traceability matrix.

Validation

Validation Checks (8 Total)

Check Type Description

CHECK 1 Error Required Document Control Fields (7 fields)

CHECK 2 Error ADR Structure Completeness (required sections)

CHECK 3 Error SYS-Ready Score Validation (format, threshold)

CHECK 4 Error Upstream Traceability Tags (@brd, @prd, @ears, @bdd)

CHECK 5 Warning Decision Quality Assessment

CHECK 6 Warning Architecture Documentation (Mermaid diagrams)

CHECK 7 Warning Implementation Readiness

CHECK 8 Error Element ID Format Compliance (unified 4-segment)

Validation Tiers

Tier Type Exit Code Action

Tier 1 Error 1 Must fix before commit

Tier 2 Warning 0 Recommended to fix

Tier 3 Info 0 No action required

Pre-Commit Hooks

ADR validation is automatically enforced via pre-commit hooks:

• id: adr-core-validator name: Validate ADR core checks (validator, framework library) entry: bash ai_dev_ssd_flow/05_ADR/scripts/adr_core_validator_hook.sh stages: [pre-commit]

• id: adr-quality-gate name: Validate ADR quality gates entry: bash ai_dev_ssd_flow/05_ADR/scripts/adr_quality_gate_hook.sh stages: [pre-commit]

• id: adr-sys-ready-score name: Validate ADR SYS-Ready score (≥90%) entry: bash ai_dev_ssd_flow/05_ADR/scripts/adr_sys_ready_score_hook.sh stages: [pre-commit]

Manual execution (for testing without committing):

pre-commit run adr-core-validator --all-files pre-commit run adr-quality-gate --all-files pre-commit run adr-sys-ready-score --all-files

Quality Gates Enforced:

• ✅ ADR structure compliance (11 sections MVP)

• ✅ SYS-Ready score ≥90% for Accepted status

• ✅ Metadata and tags (adr, layer-5-artifact)

• ✅ Upstream traceability (@brd, @prd, @ears, @bdd)

• ✅ Element ID format (ADR.NN.TT.SS)

• ✅ No placeholder text in approved documents

• ✅ Architecture diagrams (Mermaid required)

• ✅ Decision quality and alternatives analysis

Automated Validation

Per-document validation (Phase 1)

python ai_dev_ssd_flow/scripts/validate_cross_document.py --document docs/05_ADR/ADR-NN_slug.md --auto-fix

Layer validation (Phase 2) - run when all ADR documents complete

python ai_dev_ssd_flow/scripts/validate_cross_document.py --layer ADR --auto-fix

Cumulative tagging validation

python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py --artifact ADR-NN --expected-layers brd,prd,ears,bdd --strict

Manual Checklist

• Document Control section at top with 7 required fields

• Status field completed (Proposed/Accepted/Deprecated/Superseded)

• SYS-Ready Score with ✅ emoji and percentage

• Context explains problem and constraints

• Decision clearly stated

• Consequences analyzed (positive, negative, risks)

• Alternatives considered and documented with rejection rationale

• Verification approach defined

• Relations to other ADRs documented

• Technology Stack (ADR-000) referenced if applicable

• Cumulative tags: @brd, @prd, @ears, @bdd included

• Element IDs use unified format (ADR.NN.TT.SS)

• No legacy patterns (DEC-XXX, ALT-XXX, CON-XXX)

• Traceability matrix updated

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.

Automatic Validation Loop

LOOP:

1. Run: python ai_dev_ssd_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
2. IF errors fixed: GOTO LOOP (re-validate)
3. IF warnings fixed: GOTO LOOP (re-validate)
4. IF unfixable issues: Log for manual review, continue
5. IF clean: Mark VALIDATED, proceed

Layer-Specific Upstream Requirements

This Layer Required Upstream Tags Count

ADR (Layer 5) @brd, @prd, @ears, @bdd 4 tags

Auto-Fix Actions (No Confirmation Required)

Issue Fix Action

Missing @brd/@prd/@ears/@bdd tag Add with upstream document reference

Invalid tag format Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format

Legacy element ID (DEC-XXX, ALT-XXX, CON-XXX) Convert to ADR.NN.TT.SS format

Broken link Recalculate path from current location

Missing traceability section Insert from template

Validation Codes Reference

Code Description Severity

XDOC-001 Referenced requirement ID not found ERROR

XDOC-002 Missing cumulative tag ERROR

XDOC-003 Upstream document not found ERROR

XDOC-006 Tag format invalid ERROR

XDOC-007 Gap in cumulative tag chain ERROR

XDOC-009 Missing traceability section ERROR

Quality Gate

Blocking: YES - Cannot proceed to SYS creation until Phase 1 validation passes with 0 errors.

Common Pitfalls

• No alternatives: Must document why other options rejected

• Missing technology stack check: Always check ADR-000 first

• Vague consequences: Be specific about impacts

• No verification: Must define how to validate decision

• Missing cumulative tags: Layer 5 must include Layers 1-4 tags

• Legacy element IDs: Use ADR.NN.TT.SS not DEC-XXX/ALT-XXX/CON-XXX

• Wrong SYS-Ready Score format: Must include ✅ emoji and percentage

ADR-REF Reference Documents

For supplementary documentation related to ADR artifacts:

• Format: ADR-REF-NNN_{slug}.md

• Skill: Use doc-ref skill

• Validation: Reduced (4 checks only)

• Examples: Technology stack summaries, architecture overviews

ADR-REF Reduced Validation

Applicable Checks (4 total):

• CHECK 1 (partial): Document Control Fields (required)

• Document Revision History (required)

• Status/Context sections only (required)

• H1 ID match with filename (required)

Exempted (NO SCORES):

• SYS-Ready Score: NOT APPLICABLE

• Cumulative tags: NOT REQUIRED

• CHECK 5-7: Decision quality, architecture, implementation (exempt)

• All quality gates and downstream readiness metrics: EXEMPT

Purpose: ADR-REF documents are reference targets that other documents link to. They provide supporting information, context, or external references but do not define formal architecture decisions.

Next Skill

After creating ADR, use:

doc-sys

• Create System Requirements (Layer 6)

The SYS will:

• Implement ADR architectural decisions

• Include @brd , @prd , @ears , @bdd , @adr tags (cumulative)

• Define functional requirements and quality attributes

• Translate ADR decisions into technical requirements

Related Resources

• Template: ai_dev_ssd_flow/05_ADR/ADR-MVP-TEMPLATE.md (primary authority)

• Schema: ai_dev_ssd_flow/05_ADR/ADR_MVP_SCHEMA.yaml (machine-readable validation)

• Technology Stack: docs/05_ADR/ADR-00_technology_stack.md

• ADR Creation Rules: ai_dev_ssd_flow/05_ADR/ADR_MVP_CREATION_RULES.md

• ADR Validation Rules: ai_dev_ssd_flow/05_ADR/ADR_MVP_VALIDATION_RULES.md

• ADR README: ai_dev_ssd_flow/05_ADR/README.md

• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Section Templates (DEFAULT for all ADR documents):

• Structure: docs/05_ADR/ADR-NN/ADR-NN.S_slug.md (nested folder per document)

• Reference: ai_dev_ssd_flow/ID_NAMING_STANDARDS.md (Section-Based File Splitting)

• Note: Monolithic format allowed for small documents (≤25KB), but MUST still be in nested folder

Quick Reference

ADR Purpose: Document architectural decisions with rationale

Layer: 5

Tags Required: @brd, @prd, @ears, @bdd (4 tags)

Format: 11-section MVP structure

SYS-Ready Score: ≥90% required for "Accepted" status

Element ID Format: ADR.NN.TT.SS (Decision=10, Alternative=12, Consequence=13)

File Size: 800 lines target, 1200 max

Lifecycle States: Proposed → Accepted → Deprecated/Superseded

Critical: Always check ADR-000 Technology Stack first

Next: doc-sys

Version History

Version Date Changes Author

1.3 2026-03-06 Added cross-linking tags documentation, quality gate validation reference, and pre-commit hooks section System

1.2 2026-02-27 Migrated frontmatter to metadata ; normalized ADR references to ai_dev_ssd_flow/05_ADR MVP artifacts and existing validation scripts System

1.1 2026-02-26 Updated to 11-section MVP structure (aligned with ADR-MVP-TEMPLATE.md v1.1) System

1.0 2026-02-08 Initial skill definition with YAML frontmatter standardization System