- /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 .
blueprint-adr-validate
安装
npx skills add https://github.com/laurigates/claude-plugins --skill blueprint-adr-validate