leogodin217/arch-review

Architecture Review

Review architecture documents against implementation and principles.

Context to Load

1. CLAUDE.md - Core principles
2. docs/architecture/README.md - Architecture overview, implementation status
3. Architecture docs being reviewed (user specifies or all in docs/architecture/)
4. Relevant implementation code in src/fabulexa/

Process

Phase 1: Analysis

Code navigation: Use LSP tools for code exploration — find_definition to locate implementations, find_references to trace usages, get_hover for type info. Do not Grep for def foo or class Bar.

1. Read all specified architecture docs
2. Read corresponding implementation code
3. Compare design vs implementation
4. Identify issues in these categories:
   • Mismatch: Doc says X, code does Y
   • Missing spec: Doc references undefined behavior
   • Inconsistency: Docs contradict each other
   • Design question: Valid approaches, needs decision

Phase 2: Document Issues

Create or update docs/SCRATCHPAD.md with:

# Architecture Review Scratchpad

## Issues to Resolve

### 1. [Short title]

**Status:** Open

**Location:** [file:line or section reference]

**Problem:** [What's wrong]

**Options:** [If design question, list options A/B/C]

---

## Resolved Issues

### N. [Short title]

**Resolution:** [What was decided]

**Decision:** [Rationale and changes made]

---

Phase 3: Resolution Loop

For each issue:

1. Present the issue with context
2. Analyze options if it's a design question
3. Wait for user decision - DO NOT change docs until user approves
4. Make changes after approval
5. Update scratchpad - move to Resolved with decision rationale

Phase 4: Completion

Review is complete when:

• All issues resolved, OR
• Only nitpicky issues remain (formatting, minor wording)

If significant issues found → user may request another review round.

Key Principles

• Code is truth after implementation - docs point to code, not duplicate
• Evaluate which is better - don't blindly sync doc to code or vice versa
• Agree before changing - get user decision before modifying docs
• Document rationale - future readers need to know WHY

Output

After each round, summarize:

• Issues found: N
• Resolved: N
• Remaining: N (with brief list)

Example Usage

User: "Review simulation.md and actors.md" → Load docs, analyze, create scratchpad, present first issue, wait for decision