| name | adr-ref-guard |
| description | Quick advisory scan of markdown files for stale references to superseded/deprecated ADRs. Lightweight check — use the adr skill for full consistency audits. |
ADR Reference Guard
Check markdown files for references to superseded or deprecated ADRs. Advisory only — never auto-replace.
When to Use
This is a manual check skill — invoke it when you want to audit ADR references:
- Before a PR review, to catch stale ADR references
- After an ADR supersession, to find docs that reference the old ADR
- When the user asks to verify ADR references are current
This skill does NOT auto-activate on Write/Edit operations.
Detection Patterns
Scan the content being written/edited for:
ADR-NNNN or ADR NNNN (any digit count)- Markdown links:
[...](path/to/NNNN-*.md)
- Phrases: "as decided in ADR", "per ADR", "see ADR", "according to ADR", "defined in ADR"
Workflow
- Extract references: Identify all ADR numbers referenced in the content
- Locate ADR directory: Use Glob to find
{docs/decisions,docs/adr,adr,decisions}/[0-9][0-9][0-9][0-9]-*.md
- Find ADR files: For each referenced number, Glob for
NNNN-*.md in the ADR directory
- Check status: Read each referenced ADR file, parse YAML frontmatter
status field
- Warn if needed:
- If
status starts with superseded by: warn with the replacement ADR
- If
status is deprecated: warn about relevance
- If
status is proposed or accepted: no warning needed
Warning Format
Present warnings after the write/edit operation completes. Include the file being edited:
ADR Reference Warning (in docs/setup.md):
- ADR-0003 (Use PostgreSQL) is superseded by ADR-0007 (Use SQLite).
Consider updating the reference to ADR-0007.
- ADR-0005 (Legacy Auth) is deprecated.
Verify this reference is still relevant.
Constraints
- Never auto-replace references. Only inform the user.
- Never block the write/edit operation. Present the warning after completion.
- If multiple ADRs are referenced and some are current, only warn about the stale ones.
- If multiple stale references found, suggest running ADR consistency check for a full audit.
