Update PR visual writeup documentation to reflect new six-phase process and enhanced capture instructions

- Expanded the skill description to include a sixth phase for cleanup, detailing the restoration of the user's working tree.
- Revised the capture phases to clarify the process for capturing "before" and "after" screenshots, including the use of new UI selectors for highlighting changes.
- Updated the scope recording instructions to specify the new location for storing captured data.
- Enhanced the PR body template to better structure visual-heavy descriptions and included guidelines for pairing before/after images.
- Improved the gist upload documentation to streamline the process of hosting PR assets and clarified the use of PAT for authentication.

These changes aim to provide clearer guidance for users on utilizing the visual writeup skill effectively.

Author: mantrakp04

.agents/skills/pr-visual-writeup/SKILL.md

@@ -18,13 +18,14 @@ If the user only wants a text-only PR description, don't use this skill — it's
 
 ## The shape of the work
 
-Five phases. Phases 2 and 3 are the parallel-heavy ones — lean on subagents there.
+Six phases. Phases 2 and 3 are the parallel-heavy ones — lean on subagents there. Phase 6 is the cleanup that puts the user's working tree back.
 
-1. **Scope** — figure out which PR, which routes, which dev server, which auth
-2. **Capture (parallel)** — matrix of {page × theme × viewport}, plus scroll animations
+1. **Scope** — figure out which PR, which routes, which dev server, which auth, **which selectors are new UI**
+2. **Capture** — "after" pass first (parallel: page × theme × viewport, red borders on new UI), then stash + checkout base + capture "before" pass against the same dev server.
 3. **Process (parallel)** — convert scroll videos → GIFs (inline-playable), prep gist
 4. **Upload** — one gist, one commit, all files; get raw URLs
-5. **Compose + set** — markdown body with tables, then `gh pr edit --body-file`
+5. **Compose + set** — markdown body with before/after tables, then `gh pr edit --body-file`
+6. **Restore** — `git checkout <orig-branch>` + `git stash pop` so the user's working tree is exactly where they left it
 
 ## Phase 1 — Scope
 
@@ -34,25 +35,69 @@ Before you capture anything, know:
 - **Changed UI routes** — `gh pr diff <N> --name-only` and filter for page/route files. For Next.js look for `**/page*.tsx` / `**/*page-client.tsx`. Map route files to URL paths based on the app router convention. Ignore changes purely in backend / shared components unless they have an obvious UI surface.
 - **Dev server port** — `lsof -iTCP -sTCP:LISTEN -P -n | grep node` and `curl -s http://localhost:<port>/ | grep -oE '<title>[^<]+</title>'` to identify which port is the dashboard vs. API vs. docs vs. mock-OAuth.
 - **Auth flow** — if the app requires login, inspect the sign-in page for the OAuth provider to use, and ask the user (or infer from context) which dev account to sign in as. Mock OAuth servers typically accept any email.
+- **New-UI selectors** — for each changed route, derive a list of CSS selectors that point to the UI elements added or visibly modified in this PR. Read the diff for that route's component file(s), pick stable selectors (`data-testid`, semantic role, unique class, or a `:has()` text match) for each new/changed block. These selectors drive the red-border highlight pass on "after" captures. If a route has no visually changed elements (only behavior/copy refactor), record `[]` and skip highlighting for that route.
+- **Base ref for "before"** — `gh pr view <N> --json baseRefName` gives you the base branch (usually `dev` or `main`). The "before" pass swaps the working tree to that ref under the same dev server — see Phase 2. Skip the before pass entirely if the user says "after only" or if every route is greenfield.
+- **Working-tree state** — `git status --porcelain`. If there are uncommitted changes, they need to be stashed before the base checkout. Record whether a stash will be needed and the current branch name so you can restore exactly.
 
-Record these facts somewhere (a scratchpad file under `/tmp/<skill-workspace>/scope.md` is fine) — the parallel subagents in Phase 2 need them.
+Record all of these in `/tmp/pr-<N>-visuals/scope.md` — the Phase 2 subagents need them.
 
-## Phase 2 — Parallel capture
+## Phase 2 — Capture
 
-This is the skill's core trick. You have N pages × M themes × K viewports of screenshots to take. If you do this in one browser, you navigate sequentially — 9 × 2 × 2 = 36 navigations at ~5s each = 3 minutes. If you fan out, you do it in ~45s.
+Two ordered passes against a **single** dev server. The "after" pass runs first while the head branch is checked out; then we swap the working tree to the base ref (same server, same port, HMR rebuilds) and run the "before" pass.
 
-### Fan-out plan
+### Pass 1 — "after" (parallel)
 
-Spawn one subagent per **(theme, viewport)** combination. Each subagent owns a named `agent-browser` session, authenticates once, captures every page in its assigned theme/viewport, and returns the output directory. Typical combinations:
+The head branch is already checked out and the dev server is already running, so this is just the parallel matrix you started with.
 
-- `light-standard` (1920×1200, theme=light)
-- `dark-standard` (1920×1200, theme=dark)
-- `light-wide` (2560×1440, theme=light, a subset of pages)
-- `dark-wide` (2560×1440, theme=dark, a subset of pages)
+Spawn one subagent per **(theme, viewport)** combination. Each owns a named `agent-browser` session, authenticates once, captures every page in its slice with **red borders injected on new-UI selectors**, and returns the output directory.
 
-Widescreen captures are usually only worth taking for the "flagship" pages (the 3-5 most important ones). Full matrix on every page is overkill.
+- `after-light-standard` (1920×1200, theme=light, red borders on)
+- `after-dark-standard`  (1920×1200, theme=dark,  red borders on)
+- `after-light-wide` / `after-dark-wide` (2560×1440, flagship pages only)
 
-**Important:** issue all Agent tool calls for capture subagents **in a single assistant message** so they run concurrently. If you spawn them one at a time across turns, you've lost the parallelism.
+Issue all Agent calls in **one assistant message** so they run concurrently. Unique `--session-name` per agent.
+
+**Red borders.** The "after" subagents inject a stylesheet that outlines the new-UI selectors recorded in Phase 1 — see the `pr-visual-highlight` block in `references/capture-patterns.md`. Inject after navigation + settle, before the screenshot. Use `outline` (not `border` — `border` shifts layout). Skip the inject for routes whose selector list is empty.
+
+**Wait for the page to be ready before every shot.** Next.js dev compiles routes on demand and the dashboard renders skeletons during data fetch. Networkidle alone is not enough — see the `wait-for-ready` recipe in `references/capture-patterns.md`. Each subagent should also do a one-time *warm-up pass* over its assigned routes before the real capture loop, so the on-demand compile cost is paid against a throwaway hit rather than the screenshot.
+
+### Pass 1.5 — swap working tree to base
+
+After Pass 1 finishes, **before** spawning Pass 2:
+
+```bash
+# 1. Record state so Phase 6 can restore it
+ORIG_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "$ORIG_BRANCH" > /tmp/pr-<N>-visuals/orig-branch.txt
+
+# 2. Stash anything dirty (including untracked) — even if scope said clean, do this defensively
+git stash push --include-untracked -m "pr-visual-writeup pr-<N> after-pass" || true
+git rev-parse stash@{0} 2>/dev/null > /tmp/pr-<N>-visuals/stash-ref.txt || rm -f /tmp/pr-<N>-visuals/stash-ref.txt
+
+# 3. Move to the base ref
+git checkout <base-ref>     # usually `dev` or `main`, from Phase 1 scope
+git pull --ff-only
+
+# 4. Give the dev server time to HMR-rebuild against the new tree
+sleep 5 && curl -fs http://localhost:<port>/ >/dev/null
+```
+
+Stash the changes **even if `git status` reported clean.** Defensive: the user might have edited a file mid-skill, and a failed checkout halfway through is much worse than a no-op `git stash pop` at the end.
+
+If the dev server doesn't recover from HMR after the checkout (some Next configs choke on large simultaneous file changes), the fallback is to restart it manually — flag this to the user rather than papering over it.
+
+### Pass 2 — "before" (parallel)
+
+Same fan-out as Pass 1, but:
+- Filename suffix is `-before-<theme>` instead of `-after-<theme>`
+- **No red-border injection.** "Before" is the unmodified baseline.
+- Skip routes that didn't exist on the base ref (greenfield) — the subagent will hit a 404; have it log and move on instead of failing the whole pass.
+- Long-tail pages are usually not worth capturing in "before" — restrict Pass 2 to the flagship set unless the user asks otherwise.
+
+Filename convention so Phase 5 can pair shots up:
+
+- `/shots/<route>-before-<theme>[-wide].png`
+- `/shots/<route>-after-<theme>[-wide].png`
 
 The exact subagent prompt pattern lives in `references/capture-patterns.md` — read it before spawning.
 
@@ -92,9 +137,10 @@ Full recipe is in `references/gist-upload.md`. Summary: create a public gist via
 Markdown structure template is in `references/pr-body-template.md`. The load-bearing patterns:
 
 - **Summary** paragraph + `Base: → Head:` + scope line (files, +lines)
-- **Screenshots** section with one subsection per "flagship" page, each using a 2-col light/dark table, then a widescreen table
-- **Other migrated surfaces** compact table for the long tail
+- **Screenshots** section with one subsection per "flagship" page, each using a 2×2 before/after × light/dark table, then a widescreen table
+- **Other migrated surfaces** compact table for the long tail (after-only)
 - **Scroll behaviour** section with a light/dark GIF table
+- A short legend noting that the red outlines on "after" shots mark the new/changed UI
 - Everything after the visual section is the usual PR body: What's new, Notes for reviewers, Test plan
 
 Set it with:
@@ -104,6 +150,25 @@ gh pr edit <N> --body-file <path-to-md>
 
 Confirm with the user before pushing if the PR is on a public repo — this is a shared-state action. On a personal fork or draft PR, go ahead.
 
+## Phase 6 — Restore the working tree
+
+The "before" pass left the repo on the base ref with the user's original changes stashed. Put it back:
+
+```bash
+ORIG=$(cat /tmp/pr-<N>-visuals/orig-branch.txt)
+git checkout "$ORIG"
+if [ -f /tmp/pr-<N>-visuals/stash-ref.txt ]; then
+  git stash pop "$(cat /tmp/pr-<N>-visuals/stash-ref.txt)" || {
+    echo "stash pop hit conflicts — leaving stash in place"
+    git stash list | head -5
+  }
+fi
+```
+
+Do this **even if Phase 5 failed**, or the user is stuck on the wrong branch with their work hidden in a stash. If `git stash pop` conflicts, leave the stash alone and surface the conflict to the user explicitly — never auto-resolve.
+
+After restore: `git status` and `git rev-parse --abbrev-ref HEAD` for sanity, paste the output back to the user so they can verify before continuing other work.
+
 ## A note on trust boundaries
 
 Three distinct credentials touch this workflow. Keep them straight:
@@ -133,5 +198,7 @@ Create a `/tmp/pr-<N>-visuals/` workspace to hold everything. After the PR body
 ├── clips/                    # webm + gif scroll animations
 ├── body.md                   # composed PR description
 ├── gist-id.txt               # for re-pushing if you add more shots later
-└── urls.txt                  # raw URL per file, for copy-paste
+├── urls.txt                  # raw URL per file, for copy-paste
+├── orig-branch.txt           # phase 1.5: branch to return to in phase 6
+└── stash-ref.txt             # phase 1.5: stash ref to pop in phase 6 (absent if nothing was stashed)
 ```