/blueprint:adr-validate Skill

/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-plans) | | Auditing after refactoring or changes | Quick one-time documentation review | | Regular documentation review process | General ADR reading |

Context

ADR directory exists: !find . -path '*/docs/adrs' -maxdepth 2 -type d
ADR count: !find . -path '*/docs/adrs/*' -name "*.md" -type f
Domain-tagged ADRs: !find . -path '*/docs/adrs/*' -maxdepth 3 -name '*.md' -exec grep -l "^domain:" {} +
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
Cross-workspace references (v3.3.0+, manifests with workspaces.role): Recognise these reference forms in supersedes/extends/related fields:
- ADR-NNN — local to the current workspace (existing behaviour).
- <workspace-path>/ADR-NNN — points into a sibling/child workspace. Resolve by reading <workspace-path>/docs/adrs/ from the monorepo root. Warn if the workspace is not listed in root workspaces.children.
- /ADR-NNN — points at the monorepo root's ADR set. Resolve using the manifest's workspaces.root_relative_path (for child manifests) or the current directory (for root manifests). Unresolved cross-workspace refs are reported as warnings (not errors) so they do not block validation during migration.

See REFERENCE.md for detailed checks.

Step 2b: Detect ADR-number collisions and index drift

ADR numbers are chosen at branch time but only claimed at merge time, so two in-flight ADR PRs can pick the same number and both land (issue #1585 — the FVH infrastructure #2015 collision where two ADRs both claimed 0038). Run the deterministic guard:

bash ${CLAUDE_SKILL_DIR}/scripts/check-adr-numbers.sh --project-dir "$(pwd)"

It emits the structured STATUS= / ISSUE_COUNT= convention and reports three classes (see REFERENCE.md):

duplicate_adr_number (ERROR) — two files in the working tree claim the same number.
adr_number_collision (ERROR) — a working-tree ADR claims a number a different filename already holds on the base ref (origin/main). This is the pre-merge parallel-PR case, caught before the second PR merges.
adr_missing_index_row (WARN) — an ADR is not referenced from the ADR directory's README index (how the 0038 collision went unnoticed for a week).

Fold any findings into the Step 4 report. A STATUS=ERROR is a blocking collision; resolve it by renumbering the newer ADR to the next free sequential number and backfilling the README index row.

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 | | Number collisions | bash ${CLAUDE_SKILL_DIR}/scripts/check-adr-numbers.sh --project-dir "$(pwd)" |

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

Agent Skills: /blueprint:adr-validate

Install this agent skill to your local

Skill Files