review

STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.

/pbr:verify-work — Phase Review and Verification

Reference: @references/verification-overrides.md for verification override handling and gap acceptance.

References: @references/questioning.md, @references/ui-brand.md

You are the orchestrator for /pbr:verify-work. This skill verifies that what was built matches what was planned. It runs automated three-layer checks against must-haves, then walks the user through a conversational UAT (user acceptance testing) for each deliverable. Your job is to present findings clearly and help the user decide what's good enough versus what needs fixes.

Context Budget

Reference: skills/shared/context-budget.md for the universal orchestrator rules. Reference: skills/shared/agent-type-resolution.md for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• Minimize reading subagent output — read only VERIFICATION.md frontmatter for summaries. Exception: if context_window_tokens in .planning/config.json is >= 500000, reading full VERIFICATION.md bodies is permitted when gap details are needed for inline presentation.

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► REVIEWING PHASE {N}                        ║
╚══════════════════════════════════════════════════════════════╝

Where {N} is the phase number from $ARGUMENTS. Then proceed to Step 1.

Multi-Session Sync

Before any phase-modifying operations (writing VERIFICATION.md, updating STATE.md/ROADMAP.md), acquire a claim:

acquireClaim(phaseDir, sessionId)

If the claim fails (another session owns this phase), display: "Another session owns this phase. Use /pbr:progress to see active claims."

On completion or error (including all exit paths), release the claim:

releaseClaim(phaseDir, sessionId)

Prerequisites

• .planning/config.json exists
• Phase has been built: SUMMARY.md files exist in .planning/phases/{NN}-{slug}/

Event-Driven Auto-Verification

When features.goal_verification is enabled and depth is "standard" or "comprehensive", the event-handler.js hook automatically queues verification after executor completion. The hook writes .planning/.auto-verify as a signal file. The build skill's orchestrator detects this signal and spawns the verifier agent.

This is additive: /pbr:verify-work can always be invoked manually regardless of auto-verification settings. If auto-verification already ran, /pbr:verify-work re-runs verification (useful for re-checking after fixes).

Argument Parsing

Parse $ARGUMENTS according to skills/shared/phase-argument-parsing.md.

| Argument | Meaning | |----------|---------| | 3 | Review phase 3 | | 3 --auto-fix | Review phase 3, automatically diagnose and create gap-closure plans for failures | | 3 --teams | Review phase 3 with parallel specialist verifiers (functional + security + performance) | | 3 --model opus | Use opus for all verifier spawns in phase 3 (overrides config verifier_model) | | 3 --auto | Review phase 3 with auto mode — skip interactive UAT, auto-accept if verification passes | | (no number) | Use current phase from STATE.md |

Orchestration Flow

Execute these steps in order.

Step 1: Parse and Validate (inline)

1. Parse $ARGUMENTS for phase number and --auto-fix flag
2. If --model <value> is present in $ARGUMENTS, extract the value (sonnet, opus, haiku, inherit). Store as override_model. When spawning verifier Task() agents, use override_model instead of the config-derived blob.verifier_model. If an invalid value is provided, display an error and list valid values.
3. If --auto is present in $ARGUMENTS: set auto_mode = true. Log: "Auto mode enabled — skipping interactive UAT walkthrough"
4. CRITICAL — Init first. Run the init CLI call as the FIRST action after argument parsing:

``bash node plugins/pbr/scripts/pbr-tools.js init verify-work {N} ` Store the JSON result as blob. All downstream steps MUST reference blob fields instead of re-reading files. Key fields: blob.phase.dir, blob.phase.name, blob.phase.goal, blob.phase.plan_count, blob.phase.completed, blob.verifier_model, blob.has_verification, blob.prior_attempts, blob.prior_status, blob.summaries. CRITICAL (hook-enforced): Write .active-skill NOW. Write the text "review" to .planning/.active-skill` using the Write tool.

1. Resolve depth profile: run pbr-tools config resolve-depth to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
2. Validate using blob fields:
3. If blob.error: display error and stop
4. If blob.summaries is empty: display "Phase hasn't been built yet" error (see error box below)
5. If blob.phase.plan_count === 0: display "Phase has no plans" error (see error box below)
6. If no phase number given, use blob.phase.number (already resolved from STATE.md by init)
7. If .planning/.auto-verify signal file exists, read it and note the auto-verification was already queued. Delete the signal file after reading (one-shot, same pattern as auto-continue.js).
8. Resolve verification depth:
9. Run: pbr-tools trust-gate {N}
10. Parse the JSON response to get depth (light/standard/thorough)
11. Log: "Verification depth: {depth} (trust-based)"
12. Store as verification_depth for use in Step 3
13. If the command fails or graduated_verification is disabled, default to "standard"

Validation errors:

If phase directory not found, use conversational recovery:

1. Run: pbr-tools suggest-alternatives phase-not-found {slug}
2. Parse the JSON response to get available phases and suggestions (closest matches).
3. Display: "Phase '{slug}' not found. Did you mean one of these?"
4. List suggestions (if any) as numbered options.
5. Offer "Show all phases" to list available.
6. CRITICAL -- DO NOT SKIP: Present the following choice to the user via AskUserQuestion before proceeding:

Use AskUserQuestion (pattern: yes-no-pick from skills/shared/gate-prompts.md) to let the user pick a phase or abort.

• If user picks a valid phase slug: re-run with that slug.
• If user chooses to abort: stop cleanly with a friendly message.

If no SUMMARY.md files:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Phase {N} hasn't been built yet.

**To fix:** Run `/pbr:execute-phase {N}` first.

If no PLAN.md files:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Phase {N} has no plans.

**To fix:** Run `/pbr:plan-phase {N}` first.

Step 2: Check Existing Verification (inline)

Check if a VERIFICATION.md already exists using blob.has_verification and blob.prior_status from the init blob:

1. Check blob.has_verification — if true, a VERIFICATION.md exists at .planning/phases/{blob.phase.dir}/VERIFICATION.md
2. If it exists (use blob.prior_status and blob.prior_attempts for status checks):
3. Read it and check the status
4. If status: passed and no --auto-fix flag: skip to Step 4 (conversational UAT)
5. If status: gaps_found: present gaps and proceed to Step 4
6. Check for fix_plans: in frontmatter. If present, summarize each fix plan (gap, effort, tasks) before presenting gaps.
7. Classify gaps by severity: Critical (blocks functionality)