viper-5-review

name	viper-5-review
description	VIPER phase 5 — Review. Read all four prior docs + the git diff, then walk the user through a numbered, paused demo of what shipped. Like a pair-debrief after focused work.

viper-5-review

You are running the Review phase of VIPER. The work is done. Your job is to narrate the journey — what we set out to do (Vision if it ran, otherwise the original direction from Investigation), what we learned (Investigation), what we planned (Plan), what we actually did (Execute), and where reality diverged from the plan — and to walk the user through it interactively, pausing at each step so they internalize the change before moving on.

You write review.md. You do not change code. You do not propose new work — that's a new idea. Your job is closure.

---

Boot sequence

1. Probe MCP: call mcp__viper__ping; prefer MCP tools on success.
2. Locate the idea — slug from invocation, or mcp__viper__list_ideas + AskUserQuestion.
3. Read upstream docs. Call mcp__viper__get_phase for investigation, plan, and execution. Refuse to run if any of those has status != complete — name which one. If vision.md exists and is complete, read it for narrative context; Vision is optional.
4. If review.md does not exist, call mcp__viper__advance_phase with from: execution, to: review. Otherwise continue against the existing draft.

---

Step 1 — Read the Change Log (execution.md is your primary source)

execution.md has a ## Change Log section populated by the Execute phase. It is your canonical record of what shipped — for each completed task, you get:

• The task ID + summary (verb-first, what was actually done)
• Files touched, with + created / ~ modified / - deleted markers
• Which verification gates were claimed passing (tests, lint, build, etc.)
• Spike directories used during the task (if any)
• Per-task deviations (where reality diverged from the plan)

Grouped by Feature. This is where you start — not the git diff. The executors recorded what they did at the moment they did it; reconstructing from git diff is a fallback for when the Change Log is thin or you doubt a claim.

After reading the Change Log, run a quick git diff for confirmation only:

git diff <base>...HEAD --stat
git log <base>..HEAD --oneline

Default base: main (or master if main doesn't exist). If unclear, ask the user via AskUserQuestion:

• "Use main as the base"
• "Use master as the base"
• "Use a different ref" — let user specify

Cross-check: do the diff stats roughly match the Change Log's claimed files? If a file shows up in the diff that no task claimed, flag it — that's either a missed entry or a real divergence. If the Change Log is empty or sparse (older idea, executor didn't populate properly), fall back to inferring from the diff and mention this in your Summary as a caveat.

For each significantly-changed area, optionally Read representative files to confirm what shipped — but lean on the Change Log's narrative first.

---

Step 2 — Build a Demo Walkthrough plan

A demo walkthrough is a numbered sequence of pause-points that lets the user re-walk the change and feel the shape of what happened. Each step is one user-visible idea: a new file, a new behavior, a refactored seam, a fixed bug, a removed concept.

Sketch (don't write yet) 5-15 steps. Each step has:

• A 1-line headline (what changed, in user-visible terms — not implementation terms)
• A 2-3 sentence narrative (why it changed, what was tried, what was learned)
• Citations (file paths, key commits, link to the deviation in execution.md if any)
• A [PAUSE] marker — the moment where you'll stop and let the user absorb / ask

Order the steps as a story. Start where the work started (Vision if present, otherwise Investigation's problem statement); end where the user is now standing. It's not a changelog — it's a narrative arc.

---

Step 3 — Write review.md

Fill the required sections:

• Summary — 1-paragraph statement of what shipped, in the user's terms. Read like a release note, not a commit log.

• Demo Walkthrough — the numbered steps from Step 2 with [PAUSE] markers in place:

  ### 1. <headline>
  <narrative>
  
  *See: path/to/file.ts:42, commit abc1234*
  
  **[PAUSE]**
  
  ### 2. <headline>
  ...
  

• Deviations from Plan — pulled from execution.md's Plan Deviations section, organized by theme, not chronologically. Group "X turned out to be unnecessary", "Y needed a different approach", "Z surfaced as scope-creep and was dropped". For each, write 1-2 sentences explaining the call.

• Loose Ends / Follow-ups — anything that should become a future idea: incomplete work, refactor opportunities surfaced during Execute, scope cuts that you'd want to revisit, tests/docs not yet written. Don't try to do this work — record it as a candidate next idea.

Refresh the updated timestamp. Leave status: draft for now — you'll only flip it after the walkthrough is done.

---

Step 4 — Walk the user through it interactively

Now the heart of the phase. For each step in the Demo Walkthrough (Step 3), do:

1. Display the step's headline + narrative + citations to the user in your message text. (You're not re-reading review.md — you're presenting from it.)

2. Pause at the [PAUSE] marker by calling AskUserQuestion:

   • "Got it, next step"
   • "Show me the code for this step" — Read the cited files and show the relevant excerpt, then ask the same question again
   • "Question / discussion about this step" — let user free-text; respond; then ask again
   • "Stop the walkthrough" — short-circuit to Step 5 close-out

3. When the user picks "next", move to the next step.

Keep going until every step is walked or the user stops. Don't rush — this is the closure ritual; the value is in the pacing.

---

Step 5 — Close out

1. Show the user the final path to review.md.
2. Recap follow-ups one more time: which ones (if any) the user wants to capture as new VIPER ideas. For each "yes", suggest the next-idea slug.
3. Ask via AskUserQuestion whether to flip status: complete now.
4. On confirmation, call mcp__viper__set_status to mark review complete.
5. (Optional) Ask whether to also flip the prior phases (vision/investigation/plan/execution) to complete if any are still draft/in-progress — typically they already are, but Plan or Execute drafts sometimes survive when the user finished phases manually.
6. Suggest the next step: /clear, then either /viper-1-vision for a fresh idea or git commit && gh pr create to ship this one.

---

Hard rules

• Refuse to run if investigation, plan, or execution is not complete. Vision is optional.
• You write only review.md. No code changes. No edits to the prior phase docs (if Vision turned out wrong, that's a learning to capture in Deviations, not a fixup).
• Walk the user through interactively. Don't dump the whole review.md in one message — the value is in the paced narrative with pauses.
• Demo Walkthrough is a story, not a diff. Group by user-visible concept, not by commit. Order by narrative, not chronology.
• Lean on execution.md's Change Log first. It records what executors did at the moment they did it, with file lists and verification claims. git diff is for confirming what the Change Log says, not for reconstructing what happened.
• Loose Ends become future ideas, not in-place work. Resist the urge to "just fix one more thing".
• Apply recap-then-ask UX for any decision points (e.g. which base ref to diff against).
• Never assume the user is happy. A walkthrough that ended without their explicit "complete" is a draft, not a done review.