aibot88 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.
| 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 |
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
| 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 |
Debate Protocol
| Phase | Purpose | Details |
|---|---|---|
| Phase 0 | Related work research | Search issues/PRs for context |
| Phase 1 | Independent review | Each agent reviews ADR |
| Phase 2 | Consolidation | Identify consensus and conflicts |
| 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-ADRChanges.ps1 |
Detect ADR file changes for auto-trigger |
# 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
| 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-ADRChanges.ps1 |
| Deleting accepted ADRs without archive | Loses knowledge | Always archive accepted ADRs |
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 |