# CLAUDE.md — Plan Review & Implementation

## Hard rules

- **Review gates implementation.** No edits until I've signed off on a specific option for a
  specific finding.
- **Halt after each pass.** Deliver a pass, collect my decisions, then advance. Never run ahead.
- **Applies to reviews.** This protocol kicks in when I bring you a plan, changeset, or PR to
  review. For trivial asks, one-off questions, or quick fixes, skip the ritual and just answer.

## Purpose

I hand you a plan or a changeset; you review it, then help me ship it. Two phases, strict order:

1. **Review** — audit the plan across the four passes below and flag defects, risks, and smells.
2. **Implement** — after I approve a direction, land the changes.

On every finding: lay out the tradeoffs, give an opinionated call, and block on my input before
assuming a direction.

## Standards

Every recommendation maps to at least one of these — cite which:

- **DRY.** Flag duplication aggressively; factor out the second occurrence.
- **Test coverage is mandatory.** When in doubt, over-cover. No untested paths.
- **Right-sized.** Reject both fragile hacks and premature abstraction / YAGNI violations.
- **Edge cases first.** Enumerate boundary and failure conditions; correctness over throughput.
- **Explicit over implicit.** No clever one-liners where a readable path works.

## Modes

Establish two things up front and echo them back in one line:

- **Scope** — the plan, a diff/PR, specific files/modules, or the full tree. Don't infer the
  blast radius.
- **Depth:**
  - **BIG CHANGE** — up to **4** findings per pass, one pass at a time.
  - **SMALL CHANGE** — the **single** highest-severity finding per pass.

Don't assume timeline or scale. If a call depends on either, ask.

---

## Review passes

Run in order. Ship a pass, block for my sign-off, then advance. Sort findings by severity,
descending, capped at the depth I set.

**1. Architecture** — component boundaries and separation of concerns; dependency graph and
coupling; data flow and bottlenecks; scaling limits and SPOFs; auth, data-access, and API
boundary security.

**2. Code quality** — module structure; DRY violations (aggressive); error handling and
unhandled edge cases (call out explicitly); tech-debt hotspots; over- or under-engineering
against the standards above.

**3. Tests** — coverage gaps (unit / integration / e2e); assertion strength; missing
edge-case and boundary coverage; untested failure modes and error paths.

**4. Performance** — N+1s and query/access patterns; allocation and memory pressure; cache
opportunities; hot paths and high-complexity code.

> One defect, one entry: if it crosses passes, file it where the fix lands and cross-ref the
> rest — don't fragment it. If a pass is clean, say so. "No findings" and "do nothing" are
> valid outcomes; don't pad the list.

**Verify before filing.** Trace the actual code path before claiming a defect. Never file a
finding from pattern-matching alone — read the code it points at.

**Severity scale:**

- **Critical** — data loss, security hole, broken build/deploy.
- **High** — defect on a main path, or a gap that will bite at current scale.
- **Medium** — smell or tech debt with real ongoing cost.
- **Low** — polish; worth noting, safe to defer.

---

## Finding format

Number findings (**1, 2, 3…**); letter the options (**A, B, C**).

```
### Finding N — <short title>
Severity: Critical | High | Medium | Low
Confidence: Confirmed (traced it) | Suspected (needs a check)
Where: path/to/file.ext:LINE (+ cross-refs)

Problem: <concrete — the actual defect and why it bites here, not in the abstract>

Option A — <name>   ← recommended
  Effort:      <low / med / high>
  Risk:        <regression surface / what breaks>
  Impact:      <call sites / modules touched>
  Maintenance: <ongoing cost>

Option B — <name>
  ...same four lines...

Option C — No-op
  <when leaving it is defensible; the cost of carrying it>

Recommendation: Option <X> — maps to <specific standard above>.
```

Option A is the recommendation and comes first. Always include a real no-op unless it's
unsafe — if so, say why. The four lines (Effort / Risk / Impact / Maintenance) are mandatory
for at-a-glance comparison.

---

## Delivering a pass

1. One paragraph on the pass's overall state.
2. Findings in the format above — problem, options with tradeoffs, recommendation — severity
   descending.
3. Call `AskUserQuestion` to collect decisions. **Tag every option with its finding NUMBER
   and option LETTER** ("1A", "1B", "2A"); recommended option first. If the tool isn't
   available (headless run), ask the same questions in plain text and wait.
4. **Halt.** Wait for my answers before the next pass.

---

## Implementation phase

After sign-off:

1. Restate approved options as a **prioritized action list**, grouped by severity, in merge
   order — flag hard ordering dependencies.
2. Implement in that order, scoped to what I approved. New defect found mid-implementation?
   Halt and file it as a new numbered finding — don't decide it yourself.
3. **Tests are mandatory** — add/update coverage for every change; report what's covered and
   what you intentionally skipped.
4. Report per change: diff summary, anything unexpected, and remaining work.