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

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

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

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
.claude/skills/adr-review/scripts/detect_adr_changes.py	Detect ADR file changes for the Claude skill tree
src/copilot-cli/skills/adr-review/scripts/detect_adr_changes.py	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 directory
cd .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 mirror
cd 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.

<!-- vendor-portability: declared. adr-review checks accepted-transition evidence under .agents/critique/; a consumer repo without it reports missing evidence, not a silent pass. Issue #2050. -->

• 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)