phase-pr-review-loop

Phase PR Review Loop

Why this skill exists

Large changes shipped by agents fail in two characteristic ways: the plan drifts from what was built, and review findings get "fixed" in bulk without anyone verifying each fix. This loop prevents both. It has shipped multi-month, multi-agent migration work reliably because every unit is independently reviewable, every finding is closed with evidence, and a fresh session can take over by reading the ledger alone.

1. The loop

plan PR  →  plan review  →  implement (one phase = one branch)  →  phase PR
   →  reviewer briefing  →  findings as review threads
   →  fix each thread + reply with evidence  →  re-review  →  merge
   →  update the phase ledger  →  next phase

Plan first, and review the plan as a PR

1. Non-trivial phases start as a .plan.md (see the plan-writing skill): goal, in/out scope, exact files, verification commands, done-when, rollback.
2. Open the plan itself as a PR before implementation and have a different agent (or the human) review it. Plan review is where scope creep, missing gates, and wrong sequencing get caught cheaply — a finding here costs minutes; the same finding post-implementation costs a rework cycle.
3. Dated notes in the plan override its original ordering. When implementation diverges, append a dated note at the point of divergence — never let the plan lie.

One phase = one PR

1. Each phase lands as one PR off current main, on its own branch (feat/<work>-phase-<N>). Never stack multiple phases on a branch; the handoff boundary must be clean enough that a different session can take over between phases.
2. The PR description states: what the phase did, the verification that ran (commands + results), and what was explicitly NOT verified (e.g. "browser wallet smoke not run — tracked in the plan"). An honest "not verified" beats a false "done".

Reviewer briefing

1. When handing a PR to a reviewing agent, write a briefing rather than "please review": the phase's goal, the invariants that must hold (link the plan section), the riskiest diff areas, what was already verified, and what the reviewer should try to break. Ask for adversarial review — findings the author would dispute are the valuable ones.
2. The reviewer posts findings as inline review threads (one finding per thread), each with: file/line, the defect stated as a failure scenario ("with input X, Y happens"), and severity. Vague findings ("could be cleaner") are comments, not threads.