/blueprint:adr-validate

Validate Architecture Decision Records for relationship consistency, reference integrity, and domain conflicts.

Usage: /blueprint:adr-validate [--report-only]

When to Use This Skill

Use this skill when... Use alternative when...

Maintaining ADR integrity before releases Creating new ADRs (use /blueprint:derive-adr )

Auditing after refactoring or changes Quick one-time documentation review

Regular documentation review process General ADR reading

Context

• ADR directory exists: !find docs -maxdepth 1 -name 'adrs' -type d

• ADR count: !find docs/adrs -name "*.md" -type f

• Domain-tagged ADRs: !grep -l "^domain:" docs/adrs/*.md

• Flag: !echo "${1:---}"

Parameters

Parse $ARGUMENTS :

• --report-only : Output validation report without prompting for fixes

• Default: Interactive mode with remediation options

Execution

Execute complete ADR validation and remediation workflow:

Step 1: Discover all ADRs

• Check for ADR directory at docs/adrs/

• If missing → Error: "No ADRs found in docs/adrs/"

• Parse all ADR files: ls docs/adrs/*.md

• Extract frontmatter for each ADR: number, date, status, domain, supersedes, superseded_by, extends, related

Step 2: Validate reference integrity

For each ADR, validate:

• supersedes references: Verify target exists, target status = "Superseded", target has reciprocal superseded_by

• extends references: Verify target exists, warn if target is "Superseded"

• related references: Verify all targets exist, warn if one-way links

• self-references: Flag if ADR references itself

• circular chains: Detect cycles in supersession graph

See REFERENCE.md for detailed checks.

Step 3: Analyze domains

• Group ADRs by domain field

• For each domain with multiple "Accepted" ADRs → potential conflict flag

• List untagged ADRs (not errors, but recommendations)

Step 4: Generate validation report

Compile comprehensive report showing:

• Summary: Total ADRs, domain-tagged %, relationship counts, status breakdown

• Reference integrity: Supersedes, extends, related status (✅/⚠️/❌)

• Errors found: Broken references, self-references, cycles

• Warnings: Outdated extensions, one-way links

• Domain analysis: Conflicts and untagged ADRs

Step 5: Handle --report-only flag

If --report-only flag present:

• Output validation report from Step 4

• Exit without prompting for fixes

Step 6: Prompt for remediation (if interactive mode)

Ask user action via AskUserQuestion:

• Fix all automatically (update status, add reciprocal links)

• Review each issue individually

• Export report to docs/adrs/validation-report.md

• Skip for now

Execute based on selection (see REFERENCE.md).

Step 7: Update task registry

Update the task registry entry in docs/blueprint/manifest.json :

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
--arg result "${VALIDATION_RESULT:-success}"
--argjson processed "${ADRS_VALIDATED:-0}"
'.task_registry["adr-validate"].last_completed_at = $now | .task_registry["adr-validate"].last_result = $result | .task_registry["adr-validate"].stats.runs_total = ((.task_registry["adr-validate"].stats.runs_total // 0) + 1) | .task_registry["adr-validate"].stats.items_processed = $processed'
docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

Where VALIDATION_RESULT is "success", "{N} warnings", or "failed: {reason}".

Step 8: Report changes and summary

Report all changes made:

• Updated ADRs (status changes, added links)

• Remaining issues count

• Next steps recommendation

Agentic Optimizations

Context Command

Check ADR directory test -d docs/adrs && echo "YES" || echo "NO"

Count ADRs ls docs/adrs/*.md 2>/dev/null | wc -l

Extract frontmatter head -50 {file} | grep -m1 "^field:" | sed 's/^[^:]:[[:space:]]//'

Find by domain grep -l "^domain: {domain}" docs/adrs/*.md

Detect cycles Build supersession graph and traverse

For validation rules, remediation procedures, and report format details, see REFERENCE.md.