fp-review

name	fp-review
description	Phase 3 of the feature-pipeline suite. Run this after /fp-implement has pushed all commits and printed the M2 stop hook. Spawns a sandboxed sub-agent (HEAVIER) in an isolated worktree to run RED/GREEN tests against the PR diff and post a structured review comment. Use when you need an independent agent to verify correctness of implementation changes before CI runs — especially for schema mutations, CLI surface changes, or doc-touching commits. Triggers on: "review the PR", "run sandbox review", "fp-review", "Phase 3", "check the implementation", "validate the changes", "run tests on the PR", or any instruction to verify what /fp-implement just pushed.
version	3.0.0

fp-review (Phase 3 — Sandbox Review)

Spawn HEAVIER in an isolated worktree to run RED/GREEN tests, then post a structured review comment to the PR. This phase is read-and-comment only — no commits leave this phase.

The sandbox isolation matters: it prevents a flawed review from dirtying the working branch, and it forces HEAVIER to reproduce failures from a clean state rather than relying on local cache.

Setup

STATE=".agents/skills/feature-pipeline/scripts/state.sh"
branch=$($STATE get branch)
pr=$($STATE get prNumber)
phase=$($STATE get phase)

Confirm phase == 4 (set by /fp-implement on completion). If it is not 4, print a clear message explaining the pipeline order and end your turn — running out of order will produce a review against incomplete or wrong commits.

HEAVIER brief

Spawn HEAVIER with isolation: worktree on $branch. Give it exactly this brief (substitute variables):

You are reviewing PR #$pr on branch $branch. Your job is to verify each changed public surface with RED/GREEN tests, then post a review comment. Do not push any commits.

1. Read the full diff:

   git diff origin/main...HEAD
   

2. For each changed public surface (function, CLI flag, schema field): a. Write a RED test that FAILS before the fix. Verify this by temporarily reverting that change, running the test, then re-applying it. b. Write a GREEN test that PASSES with the fix in place.

3. For schema-touching commits, run:

   gaia validate
   

4. For doc-touching commits, run:

   gaia dev docs --check
   

5. Post this exact comment structure to the PR via gh pr comment:

## Sandbox Review

### RED tests
| Description | Result | Notes |
|-------------|--------|-------|

### GREEN tests
| Description | Result | Notes |
|-------------|--------|-------|

### Issues found
- [ ] <description> — `<file>:<line>`

### Verdict: APPROVE / REQUEST CHANGES

After HEAVIER finishes, capture the comment URL from its output.

Phase completion

$STATE set reviewCommentUrl "<url>"
$STATE set phase 5

Print the M3 stop hook and end your turn:

╔══ STOP HOOK M3 ══════════════════════════════════════════════════════════════╗
║  Sandbox review posted — PR #<N>                                             ║
║  Review the comment, then run /fp-iterate to address findings + watch CI.   ║
╚══════════════════════════════════════════════════════════════════════════════╝

Constraints

• If HEAVIER fails to spawn, write .fp-handover.md with the diff URL and branch name so a human can complete the review manually. End your turn — do not attempt the review yourself; the sandbox isolation is the point.
• Do not push any commits. This phase is read + comment only.