flow-code-epic-review

name	flow-code-epic-review
description	Use when all epic tasks are done and need a final review before closing. Triggers on /flow-code:epic-review.
tier	3
user-invocable	false

Epic Completion Review Mode

Read workflow.md for detailed phases and anti-patterns.

Verify that the combined implementation of all epic tasks satisfies the spec requirements. This is NOT a code quality review (that's impl-review's job) — this confirms spec compliance only.

Role: Epic Review Coordinator (NOT the reviewer) Backends: RepoPrompt (rp) or Codex CLI (codex)

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:

FLOWCTL="$HOME/.flow/bin/flowctl"

Backend Selection

Priority (first match wins):

1. --review=rp|codex|none argument
2. FLOW_REVIEW_BACKEND env var (rp, codex, none)
3. .flow/config.json → review.backend
4. Error - no auto-detection

Parse from arguments first

Check $ARGUMENTS for:

• --review=rp or --review rp → use rp
• --review=codex or --review codex → use codex
• --review=none or --review none → skip review

If found, use that backend and skip all other detection.

Otherwise read from config

BACKEND=$($FLOWCTL review-backend)

if [[ "$BACKEND" == "ASK" ]]; then
  echo "Error: No review backend configured."
  echo "Run /flow-code:setup to configure, or pass --review=rp|codex|none"
  exit 1
fi

echo "Review backend: $BACKEND (override: --review=rp|codex|none)"

Critical Rules

For rp backend:

1. DO NOT REVIEW CODE YOURSELF - you coordinate, RepoPrompt reviews
2. MUST WAIT for actual RP response - never simulate/skip the review
3. MUST use setup-review - handles window selection + builder atomically
4. DO NOT add --json flag to chat-send - it suppresses the review response
5. Re-reviews MUST stay in SAME chat - omit --new-chat after first review

For codex backend:

1. Use $FLOWCTL codex completion-review exclusively
2. Pass --receipt for session continuity on re-reviews
3. Parse verdict from command output

For all backends:

• If REVIEW_RECEIPT_PATH set: write receipt after SHIP verdict (RP writes manually after fix loop; codex writes automatically via --receipt)
• Any failure → output <promise>RETRY</promise> and stop

FORBIDDEN:

• Self-declaring SHIP without actual backend verdict
• Mixing backends mid-review (stick to one)
• Skipping review silently (must inform user and exit cleanly when backend is "none")

Input

Arguments: $ARGUMENTS Format: <epic-id> [--review=rp|codex|none]

• Epic ID - Required, e.g. fn-1 or fn-22-53k
• --review - Optional backend override

Workflow

See workflow.md for full details on each backend.

FLOWCTL="$HOME/.flow/bin/flowctl"
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

Step 0: Parse Arguments

Parse $ARGUMENTS for:

• First positional arg matching fn-* → EPIC_ID
• --review=<backend> → backend override
• Remaining args → focus areas

Step 0b: Auto-run epic audit (advisory)

Before invoking the human review backend, generate (or reuse) an epic-audit receipt. This is advisory context only — the audit NEVER blocks review and its recommendations are not treated as fix-required.

AUDIT_OUT=$($FLOWCTL epic audit "$EPIC_ID" --json 2>/dev/null || true)
AUDIT_RECEIPT=$(echo "$AUDIT_OUT" | grep -o '"receipt_path"[^,}]*' | cut -d'"' -f4)

If $AUDIT_RECEIPT exists, read it and surface the summary (coverage score, top gaps) as part of the review context passed to the backend. If a receipt <24h old exists the command reuses it automatically; pass --force only when the task list changed materially since last audit.

The auditor's recommendations are advisory notes, NOT blocking findings. Do not enter the fix loop based on audit output alone.

Step 1: Detect Backend

Run backend detection from SKILL.md above. Then branch:

Codex Backend

RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/completion-review-receipt.json}"

$FLOWCTL codex completion-review "$EPIC_ID" --receipt "$RECEIPT_PATH"
# Output includes VERDICT=SHIP|NEEDS_WORK

On NEEDS_WORK: fix code, commit, re-run (receipt enables session continuity).

RepoPrompt Backend

⚠️ STOP: You MUST read and execute workflow.md now.

Go to the "RepoPrompt Backend Workflow" section in workflow.md and execute those steps. Do not proceed here until workflow.md phases are complete.

The workflow covers:

1. Gather context (epic spec, tasks, changed files)
2. Atomic setup (setup-review) → sets $W and $T
3. Augment selection and build review prompt
4. Send review and parse verdict

Return here only after workflow.md execution is complete.

Fix Loop (INTERNAL - do not exit to Ralph)

CRITICAL: Do NOT ask user for confirmation. Automatically fix ALL valid issues and re-review — our goal is complete spec compliance. Never use AskUserQuestion in this loop.

If verdict is NEEDS_WORK, loop internally until SHIP:

1. Parse issues from reviewer feedback (missing requirements, incomplete implementations)
2. Fix code and run tests/lints
3. Commit fixes (mandatory before re-review)
4. Re-review:
   • Codex: Re-run flowctl codex completion-review (receipt enables context)
   • RP: $FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/re-review.md (NO --new-chat)
5. Repeat until <verdict>SHIP</verdict>

CRITICAL: For RP, re-reviews must stay in the SAME chat so reviewer has context. Only use --new-chat on the FIRST review.

Goal-Backward Verification (after SHIP)

After the reviewer returns SHIP, perform one final semantic check before closing:

1. Read the epic's original goal:

   $FLOWCTL cat <epic-id>
   

   Extract the ## Overview or ## Goal section (the original user intent).

2. Ask the reviewing agent (or yourself if no backend):

   "Looking at the implemented code as it stands — does this satisfy the original goal for the end user? Answer: Yes / Partial / No, with one sentence explaining why."

3. Gate on the answer:

   • Yes → proceed to receipt + status update
   • Partial → treat as NEEDS_WORK, log the gap, enter fix loop
   • No → treat as MAJOR_RETHINK, output <promise>FAIL</promise>

This catches cases where all tests pass and spec items are checked off, but the product behavior still doesn't match what the user actually wanted.

After SHIP

Epic review passed. Next:
1) Run retrospective: `/flow-code:retro <epic-id>`
2) Ship the code: push + create PR
3) Start next epic: `/flow-code:plan <idea>`