@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/skills/review/SKILL.md

@@ -0,0 +1,711 @@
+---
+name: review
+description: "Verify the build matched the plan. Automated checks + walkthrough with you."
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion, Skill
+argument-hint: "<phase-number> [--auto-fix] [--teams] [--model <model>]"
+---
+
+**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
+
+**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.
+
+Additionally for this skill:
+- **Minimize** reading subagent output — read only VERIFICATION.md frontmatter for summaries
+
+## 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.
+
+**Step progress**: Display step progress indicators at major transitions using the pattern from `@references/ui-brand.md` § Step Progress. Show `── Step {N} of 4: {Name} ──────────────────────` before each major step begins. Steps: Load Summaries, Spawn Verifier, Review Results, Write Report.
+
+## 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) |
+| (no number) | Use current phase from STATE.md |
+
+---
+
+## Orchestration Flow
+
+Execute these steps in order.
+
+---
+
+### Step 1: Parse and Validate (inline)
+
+**Init-first pattern**: When spawning agents, pass the output of `node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs init verify-work {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
+1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
+   - 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 verifier_model. If an invalid value is provided, display an error and list valid values.
+2. Read `.planning/config.json`
+   **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
+3. Resolve depth profile: run `node ${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
+4. Validate:
+   - Phase directory exists at `.planning/phases/{NN}-{slug}/`
+   - SUMMARY.md files exist (phase has been built)
+   - PLAN.md files exist (needed for must-have extraction)
+5. If no phase number given, read current phase from `.planning/STATE.md`
+   - **Before reading STATE.md**, check it exists and is parseable:
+     If `.planning/STATE.md` does not exist or cannot be parsed (missing `---` frontmatter delimiters, no **Phase**: field), display:
+
+     ```
+     ╔══════════════════════════════════════════════════════════════╗
+     ║  ERROR                                                       ║
+     ╚══════════════════════════════════════════════════════════════╝
+
+     STATE.md is missing or malformed.
+
+     **To fix:** Run `/pbr:new-project` to initialize, or `/pbr:health` to repair.
+     ```
+
+     Stop execution.
+6. 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).
+
+**Validation errors:**
+
+If phase directory not found, use conversational recovery:
+
+1. Run: `node ${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs 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?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. 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)
+
+Reference: `skills/shared/config-loading.md` for the tooling shortcut (`phase-info`) and config field reference.
+
+Check if a VERIFICATION.md already exists from `/pbr:execute-phase`'s auto-verification step:
+
+1. Look for `.planning/phases/{NN}-{slug}/VERIFICATION.md`
+2. If it exists:
+   - Read it and check the status
+   - If `status: passed` and no `--auto-fix` flag: skip to Step 4 (conversational UAT)
+   - If `status: gaps_found`: present gaps and proceed to Step 4
+   - If `status: human_needed`: proceed to Step 4
+
+3. If it does NOT exist: proceed to Step 3 (automated verification)
+
+---
+
+### Step 3: Automated Verification (delegated)
+
+**Depth profile gate:** Before spawning the verifier, resolve the depth profile. If `features.goal_verification` is false in the profile, skip automated verification and proceed directly to Step 5 (Conversational UAT). Note to user: "Automated verification skipped (depth: {depth}). Proceeding to manual review."
+
+#### Team Review Mode
+
+If `--teams` flag is present OR `config.parallelization.use_teams` is true:
+
+1. Create team output directory: `.planning/phases/{NN}-{slug}/team/` (if not exists)
+2. Display to the user: `◆ Spawning 3 verifiers in parallel (functional, security, performance)...`
+
+   Spawn THREE verifier agents in parallel using Task():
+
+   **Agent 1 -- Functional Reviewer**:
+   - subagent_type: "pbr:verifier"
+   - Prompt includes: "You are the FUNCTIONAL REVIEWER in a review team. Focus on: must-haves met, code correctness, completeness, integration points. Write output to `.planning/phases/{NN}-{slug}/team/functional-VERIFY.md`."
+
+   **Agent 2 -- Security Auditor**:
+   - subagent_type: "pbr:verifier"
+   - Prompt includes: "You are the SECURITY AUDITOR in a review team. Focus on: vulnerabilities, auth bypass paths, injection risks, secrets exposure, permission escalation. Write output to `.planning/phases/{NN}-{slug}/team/security-VERIFY.md`."
+
+   **Agent 3 -- Performance Analyst**:
+   - subagent_type: "pbr:verifier"
+   - Prompt includes: "You are the PERFORMANCE ANALYST in a review team. Focus on: N+1 queries, memory leaks, unnecessary allocations, bundle size impact, blocking operations. Write output to `.planning/phases/{NN}-{slug}/team/performance-VERIFY.md`."
+
+3. Wait for all three to complete
+4. Display to the user: `◆ Spawning synthesizer...`
+
+   Spawn synthesizer:
+   - subagent_type: "pbr:synthesizer"
+   - Prompt: "Read all *-VERIFY.md files in `.planning/phases/{NN}-{slug}/team/`. Synthesize into a unified VERIFICATION.md. Merge pass/fail verdicts -- a must-have fails if ANY reviewer flags it. Combine gap lists. Security and performance findings go into dedicated sections."
+5. Proceed to UAT walkthrough with the unified VERIFICATION.md
+
+If teams not enabled, proceed with existing single-verifier flow.
+
+Reference: `references/agent-teams.md`
+
+#### Single-Verifier Flow (default)
+
+Display to the user: `◆ Spawning verifier...`
+
+Spawn a verifier Task() to run three-layer checks:
+
+```
+Task({
+  subagent_type: "pbr:verifier",
+  // After verifier completes, check for: ## VERIFICATION COMPLETE
+  prompt: <verifier prompt>
+})
+```
+
+**Path resolution**: Before constructing any agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.cjs or template references included in the prompt.
+
+#### Verifier Prompt Template
+
+Read `${CLAUDE_SKILL_DIR}/templates/verifier-prompt.md.tmpl` and use its content as the verifier prompt.
+
+**Prepend this block to the verifier prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/PLAN-*.md — must-haves to verify against
+2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — executor build summaries
+3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
+</files_to_read>
+```
+
+**Placeholders to fill before sending:**
+- `{For each PLAN.md file in the phase directory:}` — inline each plan's must_haves frontmatter block
+- `{For each SUMMARY.md file in the phase directory:}` — provide manifest table with file paths and status from frontmatter. The verifier reads full content from disk via Read tool.
+- `{NN}-{slug}` — the phase directory name
+- `{N}` — the phase number
+- `{date}`, `{count}`, `{phase name}` — fill from context
+
+Wait for the verifier to complete.
+
+**After the verifier completes**, read VERIFICATION.md frontmatter and display a quick summary before the full results:
+
+```
+✓ Verifier: {passed}/{total} must-haves verified
+```
+
+Then show a brief table of must-haves with pass/fail status:
+
+```
+| Must-Have | Status |
+|-----------|--------|
+| {name}    | ✓      |
+| {name}    | ✗      |
+```
+
+Then display the overall verdict (`PASSED`, `GAPS FOUND`, or `HUMAN NEEDED`) before proceeding to the full results presentation.
+
+### Step 3a: Spot-Check Verifier Output
+
+CRITICAL (no hook): Verify verifier output before proceeding.
+
+1. **VERIFICATION.md exists**: Check `.planning/phases/{NN}-{slug}/VERIFICATION.md` exists on disk
+2. **Status field present**: Read VERIFICATION.md frontmatter — verify `status` field is present and is one of: pass, fail, partial
+3. **Must-haves checked**: Verify `must_haves_checked` count > 0 in frontmatter
+4. **Completion marker**: Look for `## VERIFICATION COMPLETE` in the Task() output
+
+If ANY spot-check fails, present the user with options: **Retry** / **Continue anyway** / **Abort**
+
+---
+
+### Step 3b: Local LLM Verification Quality Check (optional, advisory)
+
+After the verifier completes and writes VERIFICATION.md, if `config.local_llm.enabled` is `true`, run a quality classification:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs llm classify SUMMARY ".planning/phases/{NN}-{slug}/VERIFICATION.md"
+```
+
+- If classification is `"thin"` with confidence >= 0.7: warn `"⚠ Verification report appears thin on details — UAT may not catch all gaps. Consider re-running with /pbr:verify-work {N}."`
+- If the command fails or returns null: skip silently (local LLM unavailable)
+- This is advisory only — never block on the result
+
+---
+
+### Step 4: Present Verification Results (inline)
+
+Read the VERIFICATION.md frontmatter. Check the `attempt` counter.
+
+**If `attempt >= 3` AND `status: gaps_found`:** This phase has failed verification multiple times. Present escalation options instead of the normal flow:
+
+Present the escalation context:
+```
+Phase {N}: {name} — Verification Failed ({attempt} attempts)
+The same gaps have persisted across {attempt} verification attempts.
+Remaining gaps: {count}
+```
+
+Use AskUserQuestion (pattern: multi-option-escalation from `skills/shared/gate-prompts.md`):
+  question: "Phase {N} has failed verification {attempt} times with {count} persistent gaps. How should we proceed?"
+  header: "Escalate"
+  options:
+    - label: "Accept gaps"   description: "Mark as complete-with-gaps and move on"
+    - label: "Re-plan"       description: "Go back to /pbr:plan-phase {N} with gap context"
+    - label: "Debug"         description: "Spawn /pbr:debug to investigate root causes"
+    - label: "Retry"         description: "Try one more verification cycle"
+
+- **If user selects "Accept gaps":** Follow up with a second AskUserQuestion:
+    question: "Accept all gaps or pick specific ones to override?"
+    header: "Override?"
+    options:
+      - label: "Accept all"    description: "Mark phase as complete-with-gaps, accept everything"
+      - label: "Pick specific"  description: "Choose which gaps to mark as false positives"
+  - If "Accept all": Update STATE.md status to `complete-with-gaps`, update ROADMAP.md to `verified*`, add a note in VERIFICATION.md about accepted gaps. Proceed to next phase.
+  - If "Pick specific": Use the override flow from Step 6 "Gaps Found" section (present each gap for selection).
+- **If user selects "Re-plan":** Suggest `/pbr:plan-phase {N} --gaps` to create targeted fix plans.
+- **If user selects "Debug":** Suggest `/pbr:debug` with the gap details as starting context.
+- **If user selects "Retry":** Continue with normal Step 5 flow.
+
+**Otherwise**, present results normally using standardized status symbols (`✓` pass, `✗` fail, `⚠` warning — see `@references/ui-brand.md`):
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► VERIFYING                                  ║
+╚══════════════════════════════════════════════════════════════╝
+
+Phase {N}: {name} — Verification Results
+
+Status: {✓ PASSED | ✗ GAPS FOUND | ⚠ HUMAN NEEDED}
+Attempt: {attempt}
+
+Must-have truths:  {passed}/{total}
+Must-have artifacts: {passed}/{total}
+Must-have key links: {passed}/{total}
+
+{If all passed:}
+✓ All automated checks passed.
+
+{If gaps found:}
+✗ Gaps found:
+  1. {gap description} — {failed layer}
+  2. {gap description} — {failed layer}
+
+{If human needed:}
+⚠ Items requiring your verification:
+  1. {item} — {why automated check couldn't verify}
+```
+
+---
+
+### Step 5: Conversational UAT (inline)
+
+Walk the user through each deliverable one by one. This is an interactive conversation, not an automated check.
+
+**For each plan in the phase:**
+
+0. **Filter out ineligible plans**: Read each plan's SUMMARY.md `status` field. Skip plans with `status: failed`, `status: incomplete`, or `status: partial` that have zero committed tasks (check `commits` frontmatter field). Only walk through plans that completed successfully (`status: complete`) or partially with at least one committed task. For each skipped plan, note it to the user: "Skipping plan {plan_id} ({status}) — not eligible for UAT." If ALL plans in the phase are skipped, display: "No plans eligible for UAT walkthrough. All plans in Phase {N} are incomplete or failed. Run `/pbr:execute-phase {N}` to retry." and stop.
+1. Read the plan's must-haves and SUMMARY.md
+2. Present what was built:
+
+```
+Plan {plan_id}: {plan name}
+
+What was built:
+  {Brief description from SUMMARY.md}
+
+Key deliverables:
+  1. {artifact/truth 1}
+  2. {artifact/truth 2}
+  3. {artifact/truth 3}
+```
+
+3. For each must-have truth, walk the user through verification:
+
+```
+Checking: "{truth statement}"
+
+How to verify:
+  {Specific steps the user can take to check this}
+  {e.g., "Open http://localhost:3000 and click Login"}
+  {e.g., "Run `npm test` and check that auth tests pass"}
+
+Does this work as expected? [pass / fail / skip]
+```
+
+4. Record the user's assessment for each item
+
+**Keep the conversation flowing:**
+- If user says "pass": move to the next item
+- If user says "fail": ask what's wrong, record the issue
+- If user says "skip": note it and move on
+- If user has questions: answer them using the SUMMARY.md and plan context
+
+---
+
+### Step 6: Handle Results (inline)
+
+Compile the UAT results and determine next steps.
+
+#### All Items Pass
+
+If all automated checks and UAT items passed:
+
+1. **Update `.planning/ROADMAP.md` Progress table** (REQUIRED — do this BEFORE updating STATE.md):
+
+   **Tooling shortcut**: Use the CLI for atomic ROADMAP.md and STATE.md updates:
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs roadmap update-status {phase} verified
+   node ${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs state update status verified
+   node ${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs state update last_activity now
+   ```
+
+   1. Open `.planning/ROADMAP.md`
+   2. Find the `## Progress` table
+   3. Locate the row matching this phase number
+   4. Update the `Status` column to `verified`
+   5. Update the `Completed` column to the current date (YYYY-MM-DD)
+   6. Save the file — do NOT skip this step
+2. Update `.planning/STATE.md` **(CRITICAL (no hook) — update BOTH frontmatter AND body):**
+   - Frontmatter: `status: "verified"`, `progress_percent`, `last_activity`, `last_command`
+   - Body `## Current Position`: `Status:` line, `Last activity:` line, `Progress:` bar
+   - These MUST stay in sync — see `skills/shared/state-update.md`
+   - **STATE.md size limit:** Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
+3. Update VERIFICATION.md with UAT results (append UAT section)
+3. Present completion:
+
+Use the branded output from `references/ui-brand.md`:
+- If more phases remain: use the "Phase Complete" banner template
+- If this was the last phase in the current milestone: use the "Milestone Complete" banner template
+- **Milestone boundary detection:** Read ROADMAP.md and find the `## Milestone:` section containing the current phase. Check its `**Phases:** start - end` range. If the current phase equals `end`, this is the last phase in the milestone.
+- Always include the "Next Up" routing block
+
+4. If `gates.confirm_transition` is true in config AND `features.auto_advance` is NOT true:
+   - Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+     question: "Phase {N} verified. Ready to move to Phase {N+1}?"
+     header: "Continue?"
+     options:
+       - label: "Yes"  description: "Proceed to plan Phase {N+1}"
+       - label: "No"   description: "Stay on Phase {N} for now"
+   - If "Yes": suggest `/pbr:plan-phase {N+1}`
+   - If "No" or "Other": stop
+
+5. **If `features.auto_advance` is `true` AND `mode` is `autonomous` AND more phases remain:**
+   - Chain directly to plan: `Skill({ skill: "pbr:plan", args: "{N+1}" })`
+   - This continues the build→review→plan cycle automatically
+   - **If this is the last phase in the current milestone:** HARD STOP — do NOT auto-advance past milestone boundaries. Display: "auto_advance pauses at milestone boundaries — your sign-off is required."
+
+#### Gaps Found WITH `--auto-fix`
+
+If gaps were found and `--auto-fix` was specified:
+
+**Step 6a: Diagnose**
+
+Display to the user: `◆ Spawning debugger...`
+
+Spawn a debugger Task() to analyze each failure:
+
+```
+Task({
+  subagent_type: "pbr:debugger",
+  prompt: <debugger prompt>
+})
+```
+
+##### Debugger Prompt Template
+
+Read `${CLAUDE_SKILL_DIR}/templates/debugger-prompt.md.tmpl` and use its content as the debugger prompt.
+
+**Prepend this block to the debugger prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps and failure details
+2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — what was built
+3. .planning/phases/{NN}-{slug}/PLAN-*.md — original plan must-haves
+</files_to_read>
+```
+
+**Placeholders to fill before sending:**
+- `[Inline the VERIFICATION.md content]` — provide file path; debugger reads via Read tool
+- `[Inline all SUMMARY.md files for the phase]` — provide manifest table of file paths
+- `[Inline all PLAN.md files for the phase]` — provide manifest table of file paths
+
+**Step 6b: Create Gap-Closure Plans**
+
+After receiving the root cause analysis, display to the user: `◆ Spawning planner (gap closure)...`
+
+Spawn the planner in gap-closure mode:
+
+```
+Task({
+  subagent_type: "pbr:planner",
+  prompt: <gap planner prompt>
+})
+```
+
+##### Gap Planner Prompt Template
+
+Read `${CLAUDE_SKILL_DIR}/templates/gap-planner-prompt.md.tmpl` and use its content as the gap planner prompt.
+
+**Prepend this block to the gap planner prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps to close
+2. .planning/phases/{NN}-{slug}/PLAN-*.md — existing plans for context
+3. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+</files_to_read>
+```
+
+**Placeholders to fill before sending:**
+- `[Inline VERIFICATION.md]` — provide file path; planner reads via Read tool
+- `[Inline the debugger's root cause analysis]` — keep inline (already in conversation context)
+- `[Inline all existing PLAN.md files for this phase]` — provide manifest table of file paths
+- `[Inline CONTEXT.md if it exists]` — provide file path; planner reads via Read tool
+- `{NN}-{slug}` — the phase directory name
+
+**Step 6c: Validate gap-closure plans (conditional)**
+
+If `features.plan_checking` is true in config:
+- Display to the user: `◆ Spawning plan checker...`
+- Spawn plan checker Task() on the new gap-closure plans
+- Same process as `/pbr:plan-phase` Step 6
+
+**Step 6d: Present gap-closure plans to user**
+
+```
+Auto-fix analysis complete.
+
+Gaps found: {count}
+Root causes identified: {count}
+Gap-closure plans created: {count}
+
+Plans:
+  {plan_id}: {name} — fixes: {gap description} ({difficulty})
+  {plan_id}: {name} — fixes: {gap description} ({difficulty})
+
+Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prompts.md`):
+  question: "Approve these {count} gap-closure plans?"
+  header: "Approve?"
+  options:
+    - label: "Approve"          description: "Proceed — I'll suggest the build command"
+    - label: "Review first"     description: "Let me review the plans before approving"
+    - label: "Fix manually"     description: "I'll fix these gaps myself"
+
+- If "Approve": suggest `/pbr:execute-phase {N} --gaps-only`
+- If "Review first" or "Other": present the full plan files for inspection
+- If "Fix manually": suggest relevant files to inspect based on gap details
+
+#### Gaps Found WITHOUT `--auto-fix`
+
+If gaps were found and `--auto-fix` was NOT specified:
+
+1. List all gaps clearly
+2. **Default to auto-fix** — offer it as the recommended action, not a hidden flag
+
+```
+Phase {N}: {name} — Gaps Found
+
+{count} verification gaps need attention:
+
+1. {gap description}
+   Layer failed: {existence | substantiveness | wiring}
+   Details: {what's wrong}
+
+2. {gap description}
+   ...
+
+Use AskUserQuestion (pattern: multi-option-gaps from `skills/shared/gate-prompts.md`):
+  question: "{count} verification gaps need attention. How should we proceed?"
+  header: "Gaps"
+  options:
+    - label: "Auto-fix"  description: "Diagnose root causes and create fix plans (recommended)"
+    - label: "Override"   description: "Accept specific gaps as false positives"
+    - label: "Manual"     description: "I'll fix these myself"
+    - label: "Skip"       description: "Save results for later"
+
+**If user selects "Auto-fix":** proceed with the same Steps 6a-6d as the `--auto-fix` flow above (diagnose, create gap-closure plans, validate, present). This is the default path.
+
+**If user selects "Override":** present each gap and ask which ones to accept. For each accepted gap, collect a reason. Add to VERIFICATION.md frontmatter `overrides` list:
+```yaml
+overrides:
+  - must_have: "{text}"
+    reason: "{user's reason}"
+    accepted_by: "user"
+    accepted_at: "{ISO date}"
+```
+After adding overrides, re-evaluate: if all remaining gaps are now overridden, mark status as `passed`. Otherwise, offer auto-fix for the remaining non-overridden gaps.
+
+**If user selects "Manual":** suggest relevant files to inspect based on the gap details.
+
+**If user selects "Skip":** save results and exit.
+
+---
+
+## UAT Result Recording
+
+After conversational UAT, append UAT results to VERIFICATION.md:
+
+```markdown
+## User Acceptance Testing
+
+| # | Item | Automated | UAT | Final Status |
+|---|------|-----------|-----|-------------|
+| 1 | {must-have} | PASS | PASS | VERIFIED |
+| 2 | {must-have} | PASS | FAIL | GAP |
+| 3 | {must-have} | GAP | — | GAP |
+| 4 | {must-have} | PASS | SKIP | UNVERIFIED |
+
+UAT conducted: {date}
+Items verified: {count}
+Items passed: {count}
+Items failed: {count}
+Items skipped: {count}
+```
+
+---
+
+## Integration Verification (optional)
+
+If `features.integration_verification: true` AND this phase depends on prior phases:
+
+After Step 3, also check cross-phase integration:
+- Read SUMMARY.md `provides` and `requires` from this phase and dependent phases
+- Verify that exports from prior phases are used in this phase's code
+- Verify that this phase's outputs are compatible with future phase expectations
+- Include integration findings in Step 4 presentation
+
+---
+
+## Error Handling
+
+### Verifier agent fails
+If the verifier Task() fails, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Automated verification failed.
+
+**To fix:** We'll do a manual walkthrough instead.
+```
+Fall back to manual UAT only (skip automated checks).
+
+### No must-haves to check
+If plans have empty must_haves:
+- Warn user: `⚠ Plans don't have defined must-haves. UAT will be based on plan descriptions only.`
+- Use SUMMARY.md content as the basis for UAT
+
+### User can't verify something
+If user can't verify an item (e.g., needs server running, needs credentials):
+- Mark as SKIP
+- Record what's needed
+- Suggest how to verify later
+
+### Debugger fails during auto-fix
+If the debugger Task() fails, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Auto-diagnosis failed.
+
+**To fix:** Create gap-closure plans based on the verification report alone.
+```
+Ask user: "Would you like to proceed with gap-closure plans without root cause analysis?"
+
+---
+
+## Files Created/Modified by /pbr:verify-work
+
+| File | Purpose | When |
+|------|---------|------|
+| `.planning/phases/{NN}-{slug}/VERIFICATION.md` | Verification report | Step 3 (created or updated with UAT) |
+| `.planning/phases/{NN}-{slug}/*-PLAN.md` | Gap-closure plans | Step 6b (--auto-fix only) |
+| `.planning/ROADMAP.md` | Status → `verified` + Completed date | Step 6 |
+| `.planning/STATE.md` | Updated with review status | Step 6 |
+
+---
+
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
+## Completion
+
+After review completes, always present a clear next action using the completion banners from Read `references/ui-brand.md` § "Completion Summary Templates":
+
+- **If verified (not final phase):** Use the "Phase Complete" template. Fill in phase number, name, plan count, and next phase details.
+- **If gaps remain:** Use the "Gaps Found" template. Fill in phase number, name, gap count, and gap summaries.
+- **If final phase:** Use the "Milestone Complete" template. Fill in phase count.
+
+Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block of the completion template.
+
+---
+
+## Notes
+
+For user-friendly interpretation of verification results, see `references/reading-verification.md`.
+
+- The verifier agent has NO Write/Edit tools for project source code — it can only read, check, and write VERIFICATION.md
+- Re-running `/pbr:verify-work` after gap closure triggers fresh verification
+- UAT results are conversational — user responses are captured inline
+- VERIFICATION.md is persistent and serves as the ground truth for gap closure
+- The three-layer check (existence -> substantiveness -> wiring) catches progressively deeper issues