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.