ADR Review

ADR Review

Multi-agent debate pattern for rigorous ADR validation. Orchestrates 6 specialized agents through structured review rounds until consensus or 10 rounds maximum.

Quick Start

# Manual triggers:
/​adr-review .agents/​architecture/​ADR-005-api-versioning.md
"review this ADR"
"validate ADR-005"

Automatic Detection: A Claude Code hook (Invoke-ADRChangeDetection.ps1) runs at session start and detects ADR changes, prompting you to invoke this skill. The pre-commit hook also detects staged ADR files and displays a reminder.

File Triggers

Detection: .claude/​skills/​adr-review/​scripts/​Detect-ADRChanges.ps1

When to Use

MANDATORY Triggers (automatic):

• Architect creates or updates an ADR
• ANY agent modifies .agents/​architecture/​ADR-*.md

User-Initiated Triggers (manual):

• User requests ADR review ("review this ADR", "validate this decision")
• User requests multi-perspective validation for strategic decisions

Agent Roles

Debate Protocol

Consensus: All 6 agents Accept OR Disagree-and-Commit. Max 10 rounds.

See references/​debate-protocol.md for full phase details.

Deletion Workflow

See references/​deletion-workflow.md for full workflow.

Issue Resolution

See references/​issue-resolution.md for deferral protocol.

Phase 4: Strategic Review (Principal-Level Validation)

After structural and technical review, apply strategic lenses:

Strategic Validation Checklist

Chesterton's Fence (Change Justification)

• If removing/​changing existing patterns: Original purpose documented
• Investigation evidence provided (git archaeology, interviews, documentation)
• Confirmation original problem no longer exists
• Assessment: [PASS | FAIL | N/​A]

Path Dependence (Irreversibility Recognition)

• Historical constraints identified and documented
• Reversibility assessment complete (rollback capability, vendor lock-in)
• Migration/​exit strategy defined if adding dependencies
• Irreversible decisions explicitly flagged and justified
• Assessment: [PASS | FAIL | N/​A]

Core vs Context (Investment Prioritization)

• Capability classified as Core (differentiating) or Context (commodity)
• If building Context: Justification for not buying/​outsourcing
• If Core: Competitive differentiation explained
• Assessment: [PASS | FAIL | N/​A]

Second-System Effect (Over-Engineering Detection)

• If replacing existing system: Scope boundaries explicit
• Feature list justified (not "everything we didn't do last time")
• Simplicity preservation strategy documented
• Assessment: [PASS | FAIL | N/​A]

Strategic Review Verdict

Overall Strategic Assessment: [APPROVED | CONCERNS | REJECTED]

Blocking Issues:

• [Strategic issue 1 with required mitigation]
• [Strategic issue 2 with required mitigation]

Recommendations:

• [Strategic improvement 1]
• [Strategic improvement 2]

Scripts

# Basic detection
& .claude/​skills/​adr-review/​scripts/​Detect-ADRChanges.ps1

# Compare to specific commit
& .claude/​skills/​adr-review/​scripts/​Detect-ADRChanges.ps1 -SinceCommit "abc123"

Verification Checklist

After skill invocation:

• Debate log exists at .agents/​critique/​ADR-NNN-debate-log.md
• ADR status updated (proposed/​accepted/​needs-revision)
• All P0 issues addressed or documented
• Dissent captured for Disagree-and-Commit positions
• Recommendations provided to orchestrator

Anti-Patterns

References