ADR Review
Multi-agent debate pattern for rigorous ADR validation. Orchestrates up to 6 specialized agents through structured review rounds until consensus or 10 rounds maximum.
Panel size follows the AGENTS.md trigger. The full six-agent panel runs when the ADR change touches executable enforcement or a rule other gates read. A prose-only or metadata-only edit takes a reduced panel of architect and critic. Either way, any ADR edit that is not frontmatter-only still needs the staged debate log the git_hook_policy.py adr-review job checks.
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 .project-toolkit/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 |
.project-toolkit/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
.project-toolkit/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 per debate log. A revision of the ADR text does not reset the cap. A debate closed by consensus, or by round 10 without consensus, is followed by a new debate in a new log that restarts at round 1. See Round Cap.
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 justification in the debate log |
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)
Path Dependence (Irreversibility Recognition)
Core vs Context (Investment Prioritization)
Second-System Effect (Over-Engineering Detection)
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
After skill invocation:
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) |
| architect-impact-analysis.md |
For the architect agent, not used by the debate: impact analysis deliverable |
| architect-code-organization-review.md |
For the architect agent, not used by the debate: directory structure review |
| architect-vendor-lock-in.md |
For the architect agent, not used by the debate: vendor lock-in section template |
| architect-strategic-principles.md |
For the architect agent, not used by the debate: strategic principles and legacy patterns |
1---2name: adr-review-33description: 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 .project-toolkit/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).4metadata:5 source: https://skillmd.com/skills/rjmurillo/adr-review-36---78# ADR Review910Multi-agent debate pattern for rigorous ADR validation. Orchestrates up to 6 specialized agents through structured review rounds until consensus or 10 rounds maximum.1112Panel size follows the AGENTS.md trigger. The full six-agent panel runs when the ADR change touches executable enforcement or a rule other gates read. A prose-only or metadata-only edit takes a reduced panel of architect and critic. Either way, any ADR edit that is not frontmatter-only still needs the staged debate log the `git_hook_policy.py adr-review` job checks.1314## Triggers1516| Trigger Phrase | Operation |17|----------------|-----------|18| `review this ADR` | Full 6-agent debate on specified ADR |19| `validate ADR-005` | Targeted review of specific ADR by number |20| `review this decision record` | ADR review for durable architecture/design decision records |21| `delete ADR-NNN` | Deletion review with dependency and supersession checks |22| `ADR file created, modified, or deleted` | Auto-triggered via detect_adr_changes.py |2324---2526## Quick Start2728```text29# Manual triggers:30/adr-review .project-toolkit/architecture/ADR-005-api-versioning.md31"review this ADR"32"validate ADR-005"33"review this decision record under docs/decisions"34```3536**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.3738| Input | Output | Consensus Required |39|-------|--------|-------------------|40| ADR file path | Debate log + Updated ADR | 6/6 Accept or D&C |4142## File Triggers4344| Pattern | Location | Events |45|---------|----------|--------|46| `ADR-*.md` | `.project-toolkit/architecture/` | create, update, delete |47| `ADR-*.md` | `docs/adr/` | create, update, delete |48| `ADR-*.md` | `docs/architecture/` | create, update, delete |49| `ADR-*.md` | `docs/decisions/` | create, update, delete |50| `ADR-*.md` | `architecture/decisions/` | create, update, delete |5152**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.5354## When to Use5556**MANDATORY Triggers** (automatic):5758- Architect creates or updates an ADR59- ANY agent modifies `.project-toolkit/architecture/ADR-*.md`, `docs/adr/ADR-*.md`, `docs/architecture/ADR-*.md`, `docs/decisions/ADR-*.md`, or `architecture/decisions/ADR-*.md`6061**User-Initiated Triggers** (manual):6263- User requests ADR review ("review this ADR", "validate this decision")64- User asks to review a durable design decision record or rationale for future maintainers65- User requests multi-perspective validation for strategic decisions6667## Agent Roles6869| Agent | Focus | Tie-Breaker Role |70|-------|-------|------------------|71| **architect** | Structure, governance, coherence, ADR compliance | Structural questions |72| **critic** | Gaps, risks, alignment, completeness | None |73| **independent-thinker** | Challenge assumptions, surface contrarian views | None |74| **security** | Threat models, security trade-offs | None |75| **analyst** | Root cause, evidence, feasibility | None |76| **high-level-advisor** | Priority, resolve conflicts, break ties | Decision paralysis |7778## Process7980| Phase | Purpose | Details |81|-------|---------|---------|82| **Phase 0** | Related work research | Search issues/PRs for context |83| **Phase 1** | Independent review | Each agent reviews ADR using [Zimmermann 7-question checklist](references/zimmermann-review-guidance.md) |84| **Phase 2** | Consolidation | Identify consensus and conflicts; flag [review anti-patterns](references/zimmermann-review-guidance.md) |85| **Phase 3** | Resolution | Propose updates for P0/P1 issues |86| **Phase 4** | Convergence check | Agents vote: Accept/D&C/Block |8788**Consensus**: All 6 agents Accept OR Disagree-and-Commit. Max 10 rounds per debate log. A revision of the ADR text does not reset the cap. A debate closed by consensus, or by round 10 without consensus, is followed by a new debate in a new log that restarts at round 1. See [Round Cap](references/debate-protocol.md#round-cap).8990See [references/debate-protocol.md](references/debate-protocol.md) for full phase details.9192## Deletion Workflow9394| Phase | Purpose |95|-------|---------|96| **D1** | Detection - identify deleted ADR |97| **D2** | Impact assessment - find dependencies |98| **D3** | Archival decision - archive accepted ADRs |99| **D4** | Cleanup - update references |100101See [references/deletion-workflow.md](references/deletion-workflow.md) for full workflow.102103## Issue Resolution104105| Priority | Requirement | Gate |106|----------|-------------|------|107| **P0** | Must resolve | BLOCKING |108| **P1** | Resolve OR defer with justification in the debate log | BLOCKING |109| **P2** | Document | Non-blocking |110111See [references/issue-resolution.md](references/issue-resolution.md) for deferral protocol.112113## Phase 4: Strategic Review (Principal-Level Validation)114115After structural and technical review, apply strategic lenses:116117### Strategic Validation Checklist118119#### Chesterton's Fence (Change Justification)120121- [ ] If removing/changing existing patterns: Original purpose documented122- [ ] Investigation evidence provided (git archaeology, interviews, documentation)123- [ ] Confirmation original problem no longer exists124- [ ] Assessment: [PASS | FAIL | N/A]125126#### Path Dependence (Irreversibility Recognition)127128- [ ] Historical constraints identified and documented129- [ ] Reversibility assessment complete (rollback capability, vendor lock-in)130- [ ] Migration/exit strategy defined if adding dependencies131- [ ] Irreversible decisions explicitly flagged and justified132- [ ] Assessment: [PASS | FAIL | N/A]133134#### Core vs Context (Investment Prioritization)135136- [ ] Capability classified as Core (differentiating) or Context (commodity)137- [ ] If building Context: Justification for not buying/outsourcing138- [ ] If Core: Competitive differentiation explained139- [ ] Assessment: [PASS | FAIL | N/A]140141#### Second-System Effect (Over-Engineering Detection)142143- [ ] If replacing existing system: Scope boundaries explicit144- [ ] Feature list justified (not "everything we didn't do last time")145- [ ] Simplicity preservation strategy documented146- [ ] Assessment: [PASS | FAIL | N/A]147148### Strategic Review Verdict149150**Overall Strategic Assessment**: [APPROVED | CONCERNS | REJECTED]151152**Blocking Issues**:153154- [Strategic issue 1 with required mitigation]155- [Strategic issue 2 with required mitigation]156157**Recommendations**:158159- [Strategic improvement 1]160- [Strategic improvement 2]161162## Scripts163164| Script | Purpose |165|--------|---------|166| `.claude/skills/adr-review/scripts/detect_adr_changes.py` | Detect ADR file changes for the Claude skill tree |167| `src/copilot-cli/skills/adr-review/scripts/detect_adr_changes.py` | Detect ADR file changes for the Copilot CLI mirror |168169```bash170# Basic detection from repo root171uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py172173# Skill-relative detection from the Claude skill directory174cd .claude/skills/adr-review175python3 scripts/detect_adr_changes.py --base-path ../../..176cd ../../..177178# Compare to specific commit179uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py --since-commit abc123180181# Include untracked ADR files182uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py --include-untracked183184# Copilot CLI mirror from repo root185uv run python src/copilot-cli/skills/adr-review/scripts/detect_adr_changes.py --include-untracked186187# Skill-relative detection from the Copilot CLI mirror188cd src/copilot-cli/skills/adr-review189python3 scripts/detect_adr_changes.py --base-path ../../../..190cd ../../../..191```192193## Verification Checklist194195Before marking complete, run the bundled detector to check for pending ADR changes:196197```bash198uv run python .claude/skills/adr-review/scripts/detect_adr_changes.py --include-untracked199echo "exit=$?" # must be 0; non-zero means git error or I/O failure200```201202- [ ] The detector script exited 0 (no git or I/O errors)203- [ ] 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 acceptable204205After skill invocation:206207- [ ] Debate log exists at `.project-toolkit/critique/ADR-NNN-debate-log.md` (first debate)208- [ ] If the ADR was revised after a closed debate: a new debate log exists at `.project-toolkit/critique/ADR-NNN-debate-log-2.md` (`-3`, and so on; never overwrite the closed log), restarts at round 1, and names the closed log as its prior debate log209- [ ] ADR status updated using the frontmatter enum below; use prose for review nuance210- [ ] Frontmatter `status` field present and a valid enum value: one of211 `proposed | accepted | rejected | deprecated | superseded` (ADR-073).212 A missing or out-of-enum `status` is a P1 blocker; the frontmatter enum is213 authoritative for tooling, the prose `## Status` carries the human nuance.214- [ ] If this review transitions `status` to `accepted`: the same change carries215 adr-review debate-log evidence at `.project-toolkit/critique/ADR-NNN-debate-log.md` (or a later `.project-toolkit/critique/ADR-NNN-debate-log-2.md`)216 (ADR-073 Phase-3 acceptance gate). A hand-edit to `accepted` with no217 debate-log artifact is a forgeable approval signal and MUST be rejected.218<!-- vendor-portability: declared. adr-review checks accepted-transition evidence under .project-toolkit/critique/; a consumer repo without it reports missing evidence, not a silent pass. -->219- [ ] All P0 issues addressed or documented220- [ ] Dissent captured for Disagree-and-Commit positions221- [ ] Recommendations provided to orchestrator222223## Anti-Patterns224225### Process Anti-Patterns226227| Avoid | Why | Instead |228|-------|-----|---------|229| Single-agent ADR review | Misses domain expertise | Use full 6-agent debate |230| Skipping Phase 0 | Duplicates existing work | Always research first |231| Ignoring D&C dissent | Loses important context | Document all reservations |232| Manual ADR monitoring | Error-prone | Use detect_adr_changes.py |233| Deleting accepted ADRs without archive | Loses knowledge | Always archive accepted ADRs |234235### Review Anti-Patterns (Zimmermann)236237Each agent should self-check against these. Phase 2 consolidation flags violations.238239| Anti-Pattern | Problem | Detection |240|-------------|---------|-----------|241| **Pass Through** | Few/no comments, document barely read | Agent produces no substantive findings |242| **Copy Edit** | Focuses on wording, ignores content | All findings editorial, none architectural |243| **Siding/Dead End** | Comments switch topic, deviate from ADR | Agent drifts from decision at hand |244| **Self Promotion** | Recommends reviewer's preferred solution | Agent pushes technology without objective rationale |245| **Power Game** | Authority claims instead of technical arguments | Agent uses position over evidence |246| **Offended Reaction** | Defends criticized position subjectively | Agent reacts emotionally to rationale |247| **Groundhog Day** | Same message repeated across rounds | Agent re-raises resolved issues |248249See [zimmermann-review-guidance.md](references/zimmermann-review-guidance.md) for full practices and pledges.250251## References252253| Document | Content |254|----------|---------|255| [debate-protocol.md](references/debate-protocol.md) | Full Phases 0-4 workflow |256| [deletion-workflow.md](references/deletion-workflow.md) | Phases D1-D4 workflow |257| [issue-resolution.md](references/issue-resolution.md) | P0/P1/P2 handling and deferral |258| [artifacts.md](references/artifacts.md) | Output formats and templates |259| [agent-prompts.md](references/agent-prompts.md) | Detailed agent prompt templates |260| [zimmermann-review-guidance.md](references/zimmermann-review-guidance.md) | Review practices, 7 anti-patterns, checklist, reviewer pledge (Zimmermann 2023) |261| [architect-impact-analysis.md](references/architect-impact-analysis.md) | For the `architect` agent, not used by the debate: impact analysis deliverable |262| [architect-code-organization-review.md](references/architect-code-organization-review.md) | For the `architect` agent, not used by the debate: directory structure review |263| [architect-vendor-lock-in.md](references/architect-vendor-lock-in.md) | For the `architect` agent, not used by the debate: vendor lock-in section template |264| [architect-strategic-principles.md](references/architect-strategic-principles.md) | For the `architect` agent, not used by the debate: strategic principles and legacy patterns |