Imported from Leon-Kang/issue-to-pr (SKILL.md). Install upstream with npx skills add Leon-Kang/issue-to-pr. Copyright stays with the author.

Issue to pull request

issue → recon → intel gate → plan gate → code → verify → review → push gate → (optional) PR → (optional) issue comment

Everything provider-specific lives behind one CLI, i2pr. This file is policy: where the gates are, what counts as enough information, and how feedback is triaged. Do not reach past i2pr to gh, glab, or a tracker REST API for anything it already does.

Invoking i2pr. Check once per session:

command -v i2pr || echo "use: node <SKILL_DIR>/bin/i2pr.js"

If it is on PATH, use i2pr directly. Otherwise call node <SKILL_DIR>/bin/i2pr.js, where SKILL_DIR is the directory holding this file. It needs no install step and has no dependencies. Every example below writes the short form.

The three gates

They apply to new work on an issue. Never work around them, never merge them into one message.

1. Intel gate — if the issue is under-specified, say exactly what is missing and why, then stop. Do not guess a reasonable interpretation.
2. Plan gate — present a plan and wait for explicit approval before writing to any file, creating a branch, or running a formatter.
3. Push gate — present the diff and the exact commit message, and wait for explicit approval before committing and pushing.

Approval means the user says to proceed. A question, a comment, or silence is not approval. Opening a pull request and commenting on the issue are separate opt-ins after the push gate.

Which workflow am I in

Feedback rounds skip the intel and plan gates, so getting this wrong skips the gates entirely. Never decide from the user's wording alone — phrases like "continue fixing PROJ-123" fit both cases. Check the state of the world first:

i2pr branches --key PROJ-123 --format json     # is there already a branch?
i2pr pr find --source <that branch>            # is it already under review?

When the signals disagree, ask. Guessing wrong here either re-does finished work or skips the approval the user was relying on.

Setup

Run this once. If any step fails, read references/setup.md before improvising.

i2pr config show                # what is configured, and which file each value came from
i2pr repo detect                # provider, repository and target branch from the git remote
i2pr toolchain detect           # how this repo tests, lints and formats

• Tracker access: prefer an MCP server when one is connected — it needs no credential. i2pr issue … is the path when there is no MCP, and the only path that can download an attachment. See references/trackers.md.
• Git host access: gh auth login --hostname HOST or glab auth login --hostname HOST. Never ask for or store a git host token; the CLIs own those.
• If i2pr repo detect reports TargetBranch: (unresolved), ask the user which branch to target and write it to .issue-to-pr.json. Do not assume main or develop.

Workflow 1 — list my issues

i2pr issue list --limit 20

Present them plainly. Let the user pick, or suggest the highest-priority actionable one. Do not start work off the back of a list.

Workflow 2 — fix an issue

Phase 0 — Recon (read-only: no branch, no edits)

Work the whole checklist before forming an opinion.

1. The issue and its full comment thread. i2pr issue get KEY returns both. Requirements, repro details, a branch someone already started, and prior decisions live in comments at least as often as in the description.
2. Images. The output lists every image with the text it follows. If an attachment is downloadable, fetch it and actually look at it:

   i2pr issue get KEY --download /tmp/i2pr-KEY

   Then read the file. If it is not downloadable, say which filename you could not read and what you needed from it — never describe an image you have not seen, and never write "as shown in the screenshot" on faith.
3. Prior work. i2pr branches --key KEY and i2pr pr find.
4. The code. Find and read the files this touches. Naming them is not reading them.
5. History. git log --oneline -20 -- <paths> — has this area regressed before?
6. Verification path. Which test, command, or manual step will prove the fix.

Report a short recon summary before moving on.

Phase 1 — Intel gate

Ready to plan only if all of these hold:

• The problem or goal is unambiguous.
• A bug has repro steps or a trigger; a story has acceptance criteria.
• The impact is traceable to specific files.
• The expected result is stated, not inferred.
• There is a concrete way to verify it.
• Nothing essential exists only inside an image you could not read.

If any fails, stop and ask, naming for each gap what is missing and why you need it. Offer to post the questions as an issue comment; post only if confirmed.

Phase 2 — Plan gate

Present exactly six sections: understanding / root cause (2-3 lines), files involved (concrete paths), change plan (the actual edits), verification (command, manual steps, preview URL if configured), risk and blast radius, branch and commit (from i2pr convention branch and i2pr convention commit, so the team's conventions are used rather than invented).

Then stop. Skip this gate only if the user explicitly said to for this issue.

Phase 3 — Branch (only after approval)

git status --short

If anything is uncommitted or untracked, stop and ask how to handle it. Never stash automatically.

git checkout <target> && git pull --ff-only
git checkout -b "$(i2pr convention branch --key KEY --type TYPE --summary 'SUMMARY')"

If the branch already exists, check it out and merge the target branch in. If the merge conflicts, stop and ask — do not resolve someone else's conflict silently, and do not git checkout --theirs your way out of it.

Phase 4 — Implement

Implement the approved plan and nothing else. Add or update tests. If implementation shows the plan was wrong, return to Phase 2 with a corrected plan rather than quietly widening the scope.

Phase 5 — Verify

Use the commands from i2pr toolchain detect, and only those. A (none) result means this project has no such command — that is an answer, not a problem to route around. Fix failures and re-run, up to three attempts, then report.

Phase 6 — Code review (mandatory, before the push gate)

1. Look for a review skill in this project (.cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/, and the session's skills).
2. If several match, prefer one that reviews a local diff. Nothing is pushed yet, so a skill that wants a pull request URL cannot run — and a skill that defaults to committed changes must be told to look at the uncommitted working tree, or it will review an empty diff.
3. If none exists, review it yourself against git diff <target>: does it fully address the issue, are there unhandled edge cases, is it consistent with the surrounding code, is the test coverage real.
4. Fix every valid finding, re-run Phase 5, and summarize what was found and fixed.

Phase 7 — Push gate

Show what changed in 2-3 lines, git diff <target> --stat, the verification evidence, and the exact commit message. Ask for approval. Only then:

git add -A && git commit -m "$(i2pr convention commit --key KEY --type TYPE --scope SCOPE --subject 'SUBJECT')"
git push -u origin <branch>

Phase 8 — Optional pull request and issue comment

Both are opt-in and independent. Ask which the user wants.

i2pr convention pr-body                     # the template to fill; may be the repo's own
i2pr pr create --title "$(i2pr convention commit … --format json | jq -r .prTitle)" \
               --source <branch> --body-file -

Say where the pull request will open when the repository is a fork — it targets the upstream by default. For the issue comment, see references/conventions.md; show the exact text and post only after confirmation.

Workflow 3 — apply feedback

No intel gate, no plan gate, no push gate. The issue was investigated, the plan was approved, and the branch is published; a reviewer asking for a null check does not need a six-section plan or a fourth approval.

1. Read the feedback. Anything newer than the last commit, so finished work is not re-addressed:

   i2pr pr feedback --since "$(git log -1 --format=%cI)"
   i2pr pr feedback --pr <URL>          # works from any directory

   Resolved threads and your own earlier comments are already filtered out. Also read the issue comments with the same cutoff — reviewers use whichever channel is at hand. If there is no pull request, i2pr pr feedback says so; the issue comments are then the only source, which is expected, not an error.
2. Triage in one line per item — [source] what was asked → what you will do — and start working in the same turn. This list is so the user can interrupt a misreading, not a gate.
3. Escalate single items, never the batch. Stop and ask about an item only if it is ambiguous or self-contradictory, two reviewers disagree, it needs a design change beyond this diff, it touches files outside this change, it conflicts with the acceptance criteria, it changes a public API or data schema, or you cannot reproduce it. Everything else — naming, null checks, extracted helpers, missing tests, copy — is just work. Ship the rest and ask about the one.
4. Fix surgically. Check git diff <target> and change only what was flagged. If review finds a real problem outside the feedback, report it rather than silently expanding the diff.
5. Verify and review — Phases 5 and 6.
6. Commit and push directly. The branch is already under review, so an extra round-trip buys nothing. Normal push only; --force-with-lease still needs explicit approval, because rewriting history drops reviewers' context.
7. Report what changed and the diff stat. Offer an issue comment.

Workflow 4 — plan only

Run Phase 0 and Phase 1, output the Phase 2 plan, and stop. No branch, no edits, no pull request.

Rules

1. Recon before opinion. Read the issue, its comments, and the code before saying anything about how to fix it.
2. Under-specified means stop. Name what is missing and why; never guess past the intel gate.
3. Never describe an image you have not seen. Download it and look, or say you could not.
4. No edits before plan approval; no commit or push before push-gate approval.
5. Never stash automatically; never resolve a merge conflict silently.
6. Always code-review before the push gate, and fix what it finds.
7. Conventions come from i2pr convention …, never from memory. Branch prefixes, commit format and PR body differ per repository, and the config already knows which.
8. Issue status is not yours to change unless tracker.transitions is configured. Check i2pr config show rather than assuming either way.
9. Pull requests are drafts unless configured otherwise, and pr create never opens a duplicate.
10. Issue comments are status pings — outcome and links, within the configured limits. Verify with i2pr convention check-comment and post only after the user confirms the exact text.
11. A warning on stderr is not noise. "resolved state is unknown" means you may be looking at settled threads; say so instead of dropping it.

References

• references/setup.md — first run, credentials, per-repo config
• references/trackers.md — MCP versus CLI, Jira Cloud/DC, GitHub Issues, attachments
• references/git-hosts.md — GitHub/GHES, GitLab, forks, feedback shapes
• references/conventions.md — branch, commit, PR body and comment templates