Multi-agent debate orchestration for Architecture Decision Records. Automatically triggers on ADR create/edit/delete. Coordinates architect, critic, independent-thinker, security, analyst, and high-level-advisor agents in structured debate rounds until consensus. Use when you say "review this ADR", when an ADR is created/edited/deleted, or when reviewing, accepting, or updating a decision file under .agents/architecture/, docs/architecture/, docs/decisions/, docs/adr/, or architecture/decisions/, including intent like "review this decision record" or "check this rationale for future maintainers". Do NOT use to author a new ADR (use adr-generator).
Multi-agent debate orchestration for Architecture Decision Records. Automatically triggers on ADR create/edit/delete. Coordinates architect, critic, independent-thinker, security, analyst, and high-level-advisor agents in structured debate rounds until consensus. Use when you say "review this ADR", when an ADR is created/edited/deleted, or when reviewing, accepting, or updating a decision file under .agents/architecture/, docs/architecture/, docs/decisions/, docs/adr/, or architecture/decisions/, including intent like "review this decision record" or "check this rationale for future maintainers". Do NOT use to author a new ADR (use adr-generator).
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
review this decision record
ADR review for durable architecture/design decision records
delete ADR-NNN
Deletion review with dependency and supersession checks
ADR file created, modified, or deleted
Auto-triggered via detect_adr_changes.py
Quick Start
# Manual triggers:
/adr-review .agents/architecture/ADR-005-api-versioning.md
"review this ADR"
"validate ADR-005"
"review this decision record under docs/decisions"
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/adr/
create, update, delete
ADR-*.md
docs/architecture/
create, update, delete
ADR-*.md
docs/decisions/
create, update, delete
ADR-*.md
architecture/decisions/
create, update, delete
SESSION-PROTOCOL.md
.agents/
create, update, delete
Detection: from the skill directory, run python3 scripts/detect_adr_changes.py --base-path <repo-root>. From repo root, run .claude/skills/adr-review/scripts/detect_adr_changes.py for the Claude skill tree or src/copilot-cli/skills/adr-review/scripts/detect_adr_changes.py for the Copilot CLI mirror.
When to Use
MANDATORY Triggers (automatic):
Architect creates or updates an ADR
ANY agent modifies .agents/architecture/ADR-*.md, docs/adr/ADR-*.md, docs/architecture/ADR-*.md, docs/decisions/ADR-*.md, or architecture/decisions/ADR-*.md
ANY agent modifies .agents/SESSION-PROTOCOL.md
User-Initiated Triggers (manual):
User requests ADR review ("review this ADR", "validate this decision")
User asks to review a durable design decision record or rationale for future maintainers
User requests multi-perspective validation for strategic decisions
Detect ADR file changes for the Copilot CLI mirror
# Basic detection from repo root
uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py
# Skill-relative detection from the Claude skill directorycd .claude/skills/adr-review
python3 scripts/detect_adr_changes.py --base-path ../../..
cd ../../..
# Compare to specific commit
uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py --since-commit abc123
# Include untracked ADR files
uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py --include-untracked
# Copilot CLI mirror from repo root
uv run python src/copilot-cli/skills/adr-review/scripts/detect_adr_changes.py --include-untracked
# Skill-relative detection from the Copilot CLI mirrorcd src/copilot-cli/skills/adr-review
python3 scripts/detect_adr_changes.py --base-path ../../../..
cd ../../../..
Verification Checklist
Before marking complete, run the bundled detector to check for pending ADR changes:
uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py --include-untracked
echo"exit=$?"# must be 0; non-zero means git error or I/O failure
The detector script exited 0 (no git or I/O errors)
If skill was auto-triggered by a file change, HasChanges should be true; if skill was manually invoked on an existing committed ADR, HasChanges: false is expected and acceptable
After skill invocation:
Debate log exists at .agents/critique/ADR-NNN-debate-log.md
ADR status updated using the frontmatter enum below; use prose for review nuance
Frontmatter status field present and a valid enum value: one of
proposed | accepted | rejected | deprecated | superseded (ADR-073).
A missing or out-of-enum status is a P1 blocker; the frontmatter enum is
authoritative for tooling, the prose ## Status carries the human nuance.
If this review transitions status to accepted: the same change carries
adr-review debate-log evidence at .agents/critique/ADR-NNN-debate-log.md
(ADR-073 Phase-3 acceptance gate). A hand-edit to accepted with no
debate-log artifact is a forgeable approval signal and MUST be rejected.
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