Role

Oracle

Trigger

• Before finalizing TECHSPEC-<Feature-Name>.md (or temporary .opencode/context/active_features/<feature>/tech_spec.md).
• When evaluating complex interfaces, new modalities, or major architectural shifts (e.g., swapping a core library).

Inputs

• Draft docs/architecture/TECHSPEC-<Feature-Name>.md (or temporary .opencode/context/active_features/<feature>/tech_spec.md).
• Approved requirements (REQ-*.md)
• Existing codebase patterns

Outputs

• Updated architecture spec with:
  • Multi-expert review section
  • Simplicity/modularity/YAGNI evaluation
  • Risk mitigations
  • Architecture Review Log

Steps

Phase 1: Multi-Expert Debate (For Complex Decisions)

When the architecture involves significant choices (new patterns, major refactoring, complex integrations):

1. Expert Role Nomination Identify 3 tailored expert roles for the specific problem:

   • Example for IModality: System Architect, UI/UX Interaction Lead, Performance Engineer
   • Example for database change: Database Architect, Performance Engineer, Operations Lead

2. The Debate Simulate a debate between three viewpoints:

   Expert A (Proponent):

   • Proposes the current design
   • Arguments for why this approach is best
   • Addresses anticipated concerns

   Expert B (Skeptic):

   • Identifies risks, edge cases
   • Questions "IDE Gravity" creep (over-engineering)
   • Challenges assumptions

   Expert C (Alternative):

   • Proposes a different pattern
   • Example: "Event Bus" vs "Direct Calls"
   • Explains trade-offs of alternative approach

3. Consensus & Mitigation

   • Synthesize the "Golden Path" from the debate
   • List specific mitigations for identified risks
   • Document why the chosen approach wins

Phase 2: Simplicity Checklist (Always Required)

Evaluate the architecture against core principles:

Simplicity

• Can a new team member understand this in 5 minutes?
• Is there a simpler way to achieve the same goal?
• Are we solving the right problem (not over-engineering)?

Modularity

• Can components be tested in isolation?
• Are boundaries clear and well-defined?
• Is coupling minimized?

Abstraction Boundaries

• Do interfaces hide implementation details?
• Are dependencies flowing in one direction?
• Is there clear separation of concerns?

YAGNI (You Aren't Gonna Need It)

• Is every component necessary for MVP?
• Are we building for hypothetical future requirements?
• Can deferred features be added later without breaking changes?

Scalability & Performance

• Will this handle expected load?
• Are there obvious bottlenecks?
• Is resource usage reasonable?

Phase 3: Risk Assessment

Identify and mitigate risks:

1. Technical Risks

   • New/unproven technologies
   • Complex integrations
   • Performance concerns

2. Maintenance Risks

   • Knowledge silos
   • Documentation gaps
   • Testing complexity

3. Operational Risks

   • Deployment complexity
   • Monitoring/observability
   • Rollback procedures

Phase 4: Specification Update

Update the TECHSPEC with:

1. Architecture Review Section:

   • Multi-expert debate summary (if conducted)
   • Simplicity checklist results
   • Risk mitigations
   • Open questions or follow-ups

2. Architecture Review Log:

   • Date of review
   • Changes made based on review
   • Outstanding concerns

Output Template

## Architecture Review Section

### Multi-Expert Review (if applicable)
**Expert Panel**: [Role A], [Role B], [Role C]

**Key Debate Points**:
- **[Concern]**: [Synthesized argument]

**Recommended Consensus**:
[Chosen approach and rationale]

**Risk Mitigations**:
- [ ] [Mitigation 1]
- [ ] [Mitigation 2]

### Simplicity Checklist
- [x] Simplicity: [Notes]
- [x] Modularity: [Notes]
- [x] Abstraction: [Notes]
- [x] YAGNI: [Notes]
- [x] Performance: [Notes]

### Risk Assessment
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| [Risk] | High/Med/Low | High/Med/Low | [Strategy] |

### Review Log
- [Date]: [Changes made]

When to Use Multi-Expert Debate

Use the debate when:

• Introducing new architectural patterns
• Major refactoring of core systems
• Complex integration with external systems
• Performance-critical components
• Security-sensitive features
• Any decision that "feels big"

Skip debate for:

• Minor feature additions
• Well-understood patterns
• Straightforward implementations

Gate

User must approve TECHSPEC-*.md (including review section) before Implementation.