natsukium/dotfiles/pi-review

Reviews Through pi

Run a fresh pi process so the review does not inherit the calling conversation. The reviewer inspects the repository; the calling agent verifies findings and owns any revisions.

Models

Use an explicitly requested model. Otherwise use luna for an early pass and sol for high-risk reasoning or the final pass.

Prepare the review

Write the change-specific information to a scratch file outside the repository:

# Review context
 
Target: <document or change>
Review range: <git diff, git diff --cached, or base...HEAD; omit for a document>
Revision context: <what changed and why>
Focus: <risks to examine>
Previous findings: <findings and claimed resolutions, or none>
Settled: <scope cuts and trade-offs the user already decided, or none>

Settled items are not findings: without them a reviewer re-flags every cut as a gap in each round.

For a design, attach the document with --attach. For code, let pi inspect the named Git range and surrounding source instead of copying the diff into the prompt. The fixed review criteria and output format live in ./references/reviewer.md, which the script passes itself.

Run the review

./scripts/pi-review launches pi detached from the calling shell and waits for it in a separate step, so the review survives a caller whose shell is killed or timed out. Run it from inside the target repository: it starts pi at the repository root and refuses to start elsewhere.

<skill-directory>/scripts/pi-review start --out /abs/scratch/review-1 \
  --context /abs/scratch/review-context.md [--attach /abs/path/design.md] [--model luna]
<skill-directory>/scripts/pi-review wait /abs/scratch/review-1

--model defaults to sol. wait prints the review, saves it to <out>.md, and exits 0 for PASS, 1 for BLOCKED, and 2 when pi ended without a verdict (its stderr is in <out>.err; that is not a review result).

Where the caller's command timeout is shorter than a review, pass wait --timeout <seconds> below that limit and call wait again after exit 124; the review keeps running in between. Claude Code may instead run wait as a background command and act on its completion notice. wait exits 3 when the event stream has been silent for 15 minutes (--stall); then run pi-review stop <out> and start the round once more. Stop a review only through stop, which kills the recorded pid: a pkill -f pattern naming the model also matches the calling shell's own command line.

PI_REVIEW_WORKER=1 is set by the script: pi then omits this delegation skill from the child while loading other global and project skills normally.

Iterate

1. Read the review and verify each cited location and failure mechanism.
2. Fix accepted blockers and run the relevant checks.
3. Start a fresh review with the previous findings and resolutions recorded in the

new context file. Narrow Focus as the remaining risk changes.

1. Continue until the verdict is PASS. Do not change the target for a mistaken or

out-of-scope finding; record the evidence or scope boundary in the next context. Three consecutive BLOCKED rounds suggest the problem is being framed as harder than it is and the design has grown to match. Stop patching and question the premises: which requirements the user actually stated, which ones were assumed, and what the smallest change that meets the stated ones looks like. Present that alternative next to the current design, with what each gives up, and continue only with the one the user chooses.

1. Report each round's verdict and the accepted or rejected findings to the user.