GitHub Issue to PR: End-to-End Skill for Verified Fixes

This skill turns a GitHub issue into a tested, verified pull request. You would reach for it when a task is phrased as "fix issue #123 and open a PR" or "take this bug from issue to green CI." It is not for reviewing an existing PR or answering a code question with no requested change.

What it does

The skill owns the end-to-end discipline of carrying an issue to a merged-ready PR: premise validation, duplicate sweeps, class-level fixes, and honest CI reporting. It does not reimplement the mechanics of PR creation or code review; those live in sibling skills. Instead, it sequences the work so that every step has a clear completion condition, and it forces you to verify assumptions before writing code.

In practice, this means you start by reading the live issue thread, not just the body. You sweep for existing PRs and recent commits that might already address the issue. You reproduce the bug on current code and check whether the reported behavior is actually intentional design. You define acceptance criteria and risk before implementing. You fix the smallest complete change, prove your regression test fails without the fix, run quality gates, open the PR immediately, and then shepherd CI honestly until the issue is closed with a traceable comment.

Before you start

This skill is bundled with Hermes Agent, so it is installed by default. It lives at skills/github/github-issue-to-pr and is version 0.1.0. It works on linux, macos, and windows. The author is Ben Barclay (benbarclay), and it is licensed under MIT.

You need a working gh CLI authenticated against the repository you are targeting, and a local clone of that repository. The skill relies on terminal for shell commands, read_file and search_files for code inspection, and git for history and branch management. You should be comfortable with basic Git operations and have a clear understanding of the issue you are addressing.

Procedure

1. Read the live issue: body AND full thread

Use terminal to run gh issue view --comments. The body is a snapshot from filing time; the newest comments carry the live state: partial fixes already merged, new root-cause analyses, maintainer decisions, or questions directed at you that change the task. Also read repository instructions (AGENTS.md, contribution docs) with read_file. Done when the currently requested behavior, non-goals, and any unanswered thread questions are known.

2. Sweep for existing and duplicate work

Before writing anything, run gh pr list --search "#" --state all plus at least two keyword/synonym variants of the symptom (gh pr list --search " " --state open). Popular issues attract multiple independent fixes; building a duplicate wastes the work and the credit. Also check whether a recent commit already fixed it: git log --oneline -20 -- . Done when you know every open PR and recent commit touching this issue, or that none exist.

3. Validate the premise against current code: and against design intent

Reproduce the bug or demonstrate the missing behavior on the current default branch with a failing test or fixture, using search_files and read_file to trace the reported path. Then check the second question: is the "bug" actually deliberate design? Run git log -p -S "" on the code the issue wants changed and read the original commit's intent: a missing link or restriction is often the feature. Challenge stale or flawed issue prose instead of implementing it blindly. Done when the root cause or feature gap is demonstrated in current code AND the change doesn't fight an intentional design.

4. Define acceptance and risk

List acceptance criteria, interfaces, migrations/state changes, compatibility, security/privacy, rollout, and rollback. Map every criterion to a test or explicit verification. Done when review has a finite contract.

5. Implement the smallest complete change: and fix the class

Work on an isolated branch or worktree, loading systematic-debugging or test-driven-development when the bug class calls for them. Add regression tests first, then implement. When the fix is in hand, search_files for the same bug shape at sibling call sites and fix the whole class in this PR: an incomplete fix that leaves known siblings broken is worse than none. Every changed line must trace to the issue; no drive-by cleanup. Done when targeted tests pass, the original failure no longer reproduces, and sibling sites are fixed or explicitly ruled out.

6. Prove the regression test bites (sabotage run)

Temporarily restore the old behavior of the exact function under test, run the new test, and confirm it FAILS; then restore the fix and confirm it passes. A regression test that passes with and without the fix proves nothing. Done when the test demonstrably fails on pre-fix code.

7. Run repository quality gates, then open the PR immediately

Run the formatter, lint, typecheck, and the repo's canonical test entrypoint on affected areas; use requesting-code-review on the diff. Then push and open the PR right away: the PR is what dispatches CI, and CI latency is the long pole; do not sit on finished work. Load github-pr-workflow for PR mechanics: conventional branch/commit, body linking the issue with problem, approach, tests, risk, and exclusions. Read the PR back and verify head SHA, base, title, and files. Done when the PR exists with the intended diff and CI is running.

8. Shepherd CI honestly and close the loop

Inspect live checks and failure logs via gh pr checks / gh run view --log-failed. Distinguish failures introduced by your diff from pre-existing baseline or infrastructure failures: reproduce on the default branch when unsure, and rerun once only for genuine infra flakes. Never say "green," "merged," or "released" without live evidence of that exact state. When the PR lands, comment on the issue with the PR link and a one-line explanation so the reporter gets a traceable resolution. Done when CI state, remaining blockers, and the issue thread all reflect reality.

When not to use it

Do not use this skill for reviewing an existing PR, or for answering a code question with no requested change. Those tasks have their own workflows and do not need the full issue-to-PR pipeline.

Limits and gotchas

The skill is strict about honesty: you must never claim a PR is green, merged, or released without live evidence. It also warns against common pitfalls: coding before reading issue comments, sweeping for duplicate PRs, or reading current code; "fixing" behavior that the original commit shows is intentional design; fixing a symptom at one call site while sibling sites keep the same bug; shipping a regression test that also passes without the fix; opening a PR with unrun tests or unrelated formatting churn; and claiming the issue is delivered because a PR exists.

Verification

The skill defines a clear checklist for done: full issue thread read; newest comment state reflected in the plan; duplicate-PR sweep run with issue number plus two keyword variants; premise reproduced on current code; design intent checked via git history; regression test proven to fail without the fix; sibling call sites fixed or explicitly ruled out; every changed line traces to the issue; CI state reported from live evidence only; and the issue commented with the PR link.

What pairs with this

This skill works alongside github-issues for issue management, github-pr-workflow for PR mechanics, systematic-debugging and test-driven-development for the implementation phase, and requesting-code-review for getting the diff reviewed before opening the PR.