# Verify Pr Fix

> Manually verify that a bug-fix PR actually works by reproducing the failure before the fix and confirming it is gone after, with captured evidence, then posting findings to the PR (and optionally the linked issue). Use when asked to manually verify a PR/fix, reproduce an issue and its fix, confirm a fix works end to end, or capture screenshots or clips proving a change.

- Skill: `shakacode/verify-pr-fix` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add shakacode/verify-pr-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shakacode/verify-pr-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: shakacode (https://skillmd.com/u/shakacode)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shakacode/verify-pr-fix

---


# Verify PR Fix

Prove a bug-fix PR works by **reproducing the failure first, then showing the fix removes it**, with
evidence a reader can check. A fix that "passes" means nothing unless you first showed the bug.

Resolve writing style before authoring human-facing prose. Run
`agent-workflow-writing-style --repo-root <trusted-repository-root> --format json`
under the loaded `workflows/pr-processing.md` contract before writing PR or
issue comments. Apply it only to explanatory prose; keep the output template,
captured proof, results table, caveat, and `UNKNOWN` evidence intact.

This is behavioral verification, distinct from the local lint/test loop in `.agents/skills/verify/SKILL.md`
(`$verify`) and from review skills (`$adversarial-pr-review`, `$post-merge-audit`). Use this when the
question is "does the fix actually fix the reported problem?", not "does it lint and pass CI?".

Memorable invocation: `$verify-pr-fix <PR>` or "manually verify this fix and reproduce the issue".

## Core principles

- **Show the bug before the fix.** Always capture a failing "before" and a passing "after" of the _same_
  reproduction. Skipping the "before" is the most common way a verification lies.
- **Faithful over convenient.** Reproduce through the same code path / API the product uses. If you must
  build a harness, build it on the real mechanism (the actual module, the real `cluster`/HTTP/render path),
  not a paraphrase of it.
- **Evidence before assertions.** Never claim "verified" without captured output, a state check
  (`ps`/`pgrep`, HTTP status, DOM, exit code), or a screenshot. Paste the real output, including PIDs,
  codes, and timings. Never fabricate or assume output (see `AGENTS.md`).
- **State what you did NOT exercise.** If the reproduction is mechanism-level rather than the full app, say
  so plainly and name the residual-risk path. Honesty about scope is part of the deliverable.
- **Reproduce the actual condition.** Many bugs are intermittent or race-dependent. Recreate the triggering
  condition deterministically (the right input, a settle delay, the blocking state, the concurrency) before
  concluding "no repro". A clean run can mean you never triggered the bug, not that it is absent.
- **Leave the machine clean.** Kill every process you spawned and remove scratch files. Verify with
  `pgrep`/`ps` that nothing leaked.

## Instructions

1. **Read the PR and the linked issue.** `gh pr view <n> --json title,body,files,commits,url,state` and
   `gh issue view <linked> --json title,body,url`. Extract: the claimed bug, the expected vs actual
   behavior, the reproduction the reporter described, and the validation the author already ran (look for a
   "Manual / Residual Risk" or "Validation" section — verify what they left UNKNOWN).
2. **Locate the changed surface.** Read the diff (`gh pr diff <n>` or the files in the worktree). Identify
   the exact behavioral change and the smallest observable signal that distinguishes broken from fixed
   (an orphaned process, an HTTP 500 vs 200, a hydration mismatch, a cache key collision, an exit code).
3. **Choose the cheapest faithful reproduction**, in this order:
   - **Full app run** when feasible — highest fidelity. This often means the repo's integration test
     app(s) plus `.agents/bin/test` and any repo-specific e2e/manual-testing docs for browser-visible behavior.
   - **Minimal faithful harness** when the full app is too heavy to stand up quickly (needs a license,
     real bundles, a renderer, external services). Build it on the **same real API** the product uses and
     label it mechanism-level. For example, drive the same underlying runtime/process API the product
     uses (such as Node's real `cluster` module a renderer uses) rather than booting the whole subsystem.
   - For renderer/process-level changes, follow any repo-specific validation docs (see `AGENTS.md`).
4. **Reproduce the bug (the "before").** Run the reproduction against pre-fix behavior. Get pre-fix code by
   the least invasive means: check out the parent commit in a scratch worktree, `git stash` an uncommitted
   change, check out one file at its pre-fix revision (`git checkout <fix-commit>~1 -- <file>`), or (for a
   harness) model the pre-fix path explicitly. Capture the failure. If it does not fail, you have not
   reproduced it — recreate the triggering condition (input, timing, blocking, concurrency) and retry
   before concluding anything.
5. **Verify the fix (the "after").** Restore the post-fix code first (`git stash pop`,
   `git checkout HEAD -- <file>`, or leave the worktree), then run the identical reproduction. Capture the
   now-passing result and confirm the specific signal flipped (orphans 6/6 -> 0/6, exit code, status, DOM).
   Confirm `git status` is clean so the "after" really ran against post-fix code.
6. **Capture evidence.** Save real terminal output. For a static UI/browser change, capture paired
   before/after screenshots. For interaction, transition, loading, timing, or other temporal behavior,
   capture paired short clips through the repository's browser harness. Follow the Durable Visual Evidence
   Gate for portable recorder setup, reviewer-visible evidence, and artifact handling: prefer
   `.agents/workflows/pr-processing.md`; otherwise resolve `../../workflows/pr-processing.md` relative to
   the loaded skill pack. For a shareable visual of terminal results you may render the captured output with the
   visualize tool, but the render must reproduce real output verbatim — never stage numbers.
7. **Clean up.** Kill spawned processes and remove scratch dirs/worktrees, but preserve or move locally
   prepared `human_attachment_pending` evidence to a non-scratch location until it is attached.
   Confirm nothing leaked (`pgrep -fl <marker>` should report none).
8. **Report to the PR.** Post a comment with the structured format below. Before posting to GitHub (an
   outward-facing action), confirm with the user unless they already told you to post. Write the body to a
   temp file and store its path in `comment_body_file`. Resolve `PR_BATCH_SKILL_DIR` from an explicit environment value, the `pr-batch` sibling of
   the exact loaded skill directory, or repo-local `.agents/skills/pr-batch`, in that order; stop with a
   precise blocker if none exists. Set `AGENT_COMMENT_RUNNER` to exactly `codex`, `claude`, or `cursor`,
   `AGENT_COMMENT_HOST` to the actual non-empty single-line host label, and
   `AGENT_COMMENT_TASK_OR_RUN` to the stable task or run identifier. Stop if any value is unavailable;
   do not invent attribution values. Send the file through the helper's stdin explicitly:

   ```bash
   "${PR_BATCH_SKILL_DIR}/bin/github-comment-envelope" post-issue \
     --repo "${REPO}" --number "${PR_NUMBER}" \
     --runner "${AGENT_COMMENT_RUNNER:?}" --host "${AGENT_COMMENT_HOST:?}" \
     --task-or-run "${AGENT_COMMENT_TASK_OR_RUN:?}" < "${comment_body_file}"
   ```

   For local evidence, add a repeatable
   `--attach 'path#alt text'` to that helper command for images (omit `#alt text` for video). The helper
   preserves the envelope while routing the upload through the GitHub CLI attachment path. Attachments
   require GitHub CLI 2.99.0+, GitHub.com or GitHub
   Enterprise Cloud, repository write access, and an OAuth, classic PAT, or fine-grained PAT credential;
   GitHub Actions and App tokens are unsupported. Read the posted comment back and retain rewritten durable
   URLs. Fall back to the Durable Visual Evidence Gate's browser or human path when upload is unavailable.
9. **Cross-link the issue (optional).** If asked, comment on the linked issue with a 2-3 sentence summary
   and a link to the PR comment URL returned by step 8 through the same
   `${PR_BATCH_SKILL_DIR}/bin/github-comment-envelope post-issue` helper.

## Reproduction tactics by change type

- **Process / renderer lifecycle** (signals, workers, teardown, ports): drive the real `cluster`/child
  process API; assert with `ps`/`pgrep`/`kill -0` on captured PIDs and on the master's exit code. Emulate
  the real supervisor (e.g. Foreman: signal only the master PID, SIGKILL after its ~5s window).
- **Rendering / hydration / framework output** (render output, FOUC, streaming, cache keys): boot the
  relevant integration test app, hit the affected route, compare server-rendered output vs hydrated DOM,
  watch the renderer log, diff cache keys. For browser-visible output, use paired screenshots for static
  states and paired clips for temporal behavior.
- **Generators / installers / scaffolding**: run the generator into a temp app and diff the produced files
  against expectation; for behavioral output, boot the generated app.
- **Caching / dedupe / digests**: construct the colliding or repeated inputs and assert hit/miss and that
  failed renders are not cached.
- **Types-only changes**: usually covered by `.agents/bin/build` or the repo's documented type-check command; behavioral reproduction is normally not warranted — say so rather than staging
  a fake one.

## Environment notes

- **Pre-fix-on-one-file tactic** (cheap before/after for an already-merged PR): when the fix is in a single
  file and the PR added regression specs, run the post-fix spec against the pre-fix file —
  `git checkout <fix-commit>~1 -- <file>`, run the spec (it should fail on exactly the new tests), then
  **always restore** with `git checkout HEAD -- <file>` and confirm `git status` is clean before moving on.
- **Read the changed function from git, not from memory**: when a harness needs the exact pre/post logic
  (a regex, a digest, a key format), extract it verbatim with `git show <rev>:<file>` so the reproduction
  can't drift from the real code.

## When NOT to use this skill

- Docs, comments, changelog, CI/workflow plumbing, benchmark tooling, refactors with no behavioral change,
  license-header enforcement, and pure type narrowing rarely have a user-observable runtime symptom to
  reproduce. Route those to `$verify` (local checks) or a review skill instead, and say why a behavioral
  repro adds nothing.

## Output format (PR comment)

````markdown
## Manual verification: reproduced the bug and confirmed the fix ✅ / ❌

<one line on what was verified and how (full app vs mechanism-level harness)>

### Reproduction

<how the bug was triggered; the key condition that makes it deterministic>

### Results

| Scenario              | Behavior   | Result          |
| --------------------- | ---------- | --------------- |
| Pre-fix, <condition>  | <observed> | <BROKEN signal> |
| Post-fix, <condition> | <observed> | <FIXED signal>  |

```text
<real captured output, before and after>
```

### Caveat

<what was NOT exercised; the residual-risk path that remains UNKNOWN>
````

Keep the comment evidence-first and honest about scope. End behavioral claims with the captured proof, not
adjectives.