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.

Triggers

Trigger Phrase	Operation
review this ADR	Full 6-agent debate on specified ADR
validate ADR-005	Targeted review of specific ADR by number
check architecture decision	ADR review with debate protocol
ADR file created or modified	Auto-triggered via detect_adr_changes.py
delete ADR-NNN	Deletion workflow (D1-D4)

---

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 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.

Input	Output	Consensus Required
ADR file path	Debate log + Updated ADR	6/6 Accept or D&C

File Triggers

Pattern	Location	Events
ADR-*.md	.agents/architecture/	create, update, delete
ADR-*.md	docs/architecture/	create, update, delete
SESSION-PROTOCOL.md	.agents/	create, update, delete

Detection: .claude/skills/adr-review/scripts/detect_adr_changes.py

When to Use

MANDATORY Triggers (automatic):

• Architect creates or updates an ADR
• ANY agent modifies .agents/architecture/ADR-*.md
• ANY agent modifies .agents/SESSION-PROTOCOL.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

Agent	Focus	Tie-Breaker Role
architect	Structure, governance, coherence, ADR compliance	Structural questions
critic	Gaps, risks, alignment, completeness	None
independent-thinker	Challenge assumptions, surface contrarian views	None
security	Threat models, security trade-offs	None
analyst	Root cause, evidence, feasibility	None
high-level-advisor	Priority, resolve conflicts, break ties	Decision paralysis

Process

Phase	Purpose	Details
Phase 0	Related work research	Search issues/PRs for context
Phase 1	Independent review	Each agent reviews ADR using Zimmermann 7-question checklist
Phase 2	Consolidation	Identify consensus and conflicts; flag review anti-patterns
Phase 3	Resolution	Propose updates for P0/P1 issues
Phase 4	Convergence check	Agents vote: Accept/D&C/Block

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

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

Deletion Workflow

Phase	Purpose
D1	Detection - identify deleted ADR
D2	Impact assessment - find dependencies
D3	Archival decision - archive accepted ADRs
D4	Cleanup - update references

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

Issue Resolution

Priority	Requirement	Gate
P0	Must resolve	BLOCKING
P1	Resolve OR defer with issue	BLOCKING
P2	Document	Non-blocking

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

Script	Purpose
detect_adr_changes.py	Detect ADR file changes for auto-trigger

# Basic detection
python3 .claude/skills/adr-review/scripts/detect_adr_changes.py

# Compare to specific commit
python3 .claude/skills/adr-review/scripts/detect_adr_changes.py --since-commit abc123

# Include untracked ADR files
python3 .claude/skills/adr-review/scripts/detect_adr_changes.py --include-untracked

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

Process Anti-Patterns

Avoid	Why	Instead
Single-agent ADR review	Misses domain expertise	Use full 6-agent debate
Skipping Phase 0	Duplicates existing work	Always research first
Ignoring D&C dissent	Loses important context	Document all reservations
Manual ADR monitoring	Error-prone	Use detect_adr_changes.py
Deleting accepted ADRs without archive	Loses knowledge	Always archive accepted ADRs

Review Anti-Patterns (Zimmermann)

Each agent should self-check against these. Phase 2 consolidation flags violations.

Anti-Pattern	Problem	Detection
Pass Through	Few/no comments, document barely read	Agent produces no substantive findings
Copy Edit	Focuses on wording, ignores content	All findings editorial, none architectural
Siding/Dead End	Comments switch topic, deviate from ADR	Agent drifts from decision at hand
Self Promotion	Recommends reviewer's preferred solution	Agent pushes technology without objective rationale
Power Game	Authority claims instead of technical arguments	Agent uses position over evidence
Offended Reaction	Defends criticized position subjectively	Agent reacts emotionally to rationale
Groundhog Day	Same message repeated across rounds	Agent re-raises resolved issues

See zimmermann-review-guidance.md for full practices and pledges.

References

Document	Content
debate-protocol.md	Full Phases 0-4 workflow
deletion-workflow.md	Phases D1-D4 workflow
issue-resolution.md	P0/P1/P2 handling and deferral
artifacts.md	Output formats and templates
agent-prompts.md	Detailed agent prompt templates
zimmermann-review-guidance.md	Review practices, 7 anti-patterns, checklist, reviewer pledge (Zimmermann 2023)