audit-adr

ADR Audit

Audit an Architecture Decision Record for quality, completeness, and correctness. Each issue is presented to the user one at a time with multiple resolution options, always including a research option that forks parallel code + web research agents.

Input

$ARGUMENTS — path to the ADR document, and optionally --context <path> to the context file from the gather phase.

Parse Arguments

Extract from $ARGUMENTS:

• ADR Path: First non-flag argument
• Context File Path: --context <path> (optional, enables context fidelity checks)

Process

Phase 1: Load Documents

1. Read the ADR at the provided path.
2. If --context provided, read the context file.
3. Read the audit checklist at ${CLAUDE_SKILL_DIR}/references/checklist.md.

Phase 2: Run All Checks

Run every check from the checklist against the ADR. For each check, record:

• Check name and category
• Status: PASS, WARN, or FAIL
• Details: What was found (or not found)
• Severity: 🔴 CRITICAL, 🟡 WARNING, or 🔵 INFO
• Suggested fix: How to resolve

Also scan for open questions: TODO, TBD, FIXME, [ASSUMPTION], vague/placeholder text, or any unresolved items.

Build a prioritized issue queue ordered:

1. 🔴 CRITICAL issues first
2. 🟡 WARNING issues next
3. 🔵 INFO issues last
4. ❓ Open Questions last

Phase 3: Present Summary

Show the user the full breakdown before diving in:

## ADR Audit Summary: [ADR Title]

**Document:** [path]
**Context file:** [path or "not provided"]

Found **N issues** and **M open questions**:
- 🔴 CRITICAL: [count] — must fix before proceeding
- 🟡 WARNING: [count] — should fix
- 🔵 INFO: [count] — optional improvements
- ❓ Open Questions: [count]

Starting sequential resolution...

If zero issues found, skip to Phase 5 with a PASS verdict.

Phase 4: Sequential Resolution

For each issue/question in the queue, present it with resolution options using AskUserQuestion.

Format for each issue: