issue-to-plan

name	issue-to-plan
description	Read a GitHub issue, understand the codebase, ask clarifying questions, and produce a function-level implementation plan structured as an executable prompt.
allowed-tools	Bash Read Write Glob Grep

Issue-to-Plan

Turn a GitHub issue into a function-level implementation plan that another Claude session can pick up and execute. The plan is the prompt.

When to Use

• The user says "issue to plan", "plan this issue", or "turn this issue into a plan"
• The user pastes a GitHub issue URL and asks for a plan
• The user provides an org/repo and issue number and wants an implementation plan

Input

The user provides one of:

• A GitHub issue URL (e.g., https://github.com/org/repo/issues/42)
• Org, repo, and issue number (e.g., "org/repo #42")

Extract the owner, repo, and issue number from either format.

Workflow

Follow all six steps in order. Do not skip steps. Do not start writing the plan until Step 4 is complete.

Step 1 — Fetch the Issue

Check gh is available:

gh auth status

If gh is not installed, tell the user:

"This skill requires the GitHub CLI (gh). Install it from https://cli.github.com/ and run gh auth login to authenticate."

Stop here. Do not attempt workarounds.

Check for PR URL: If the user's input contains /pull/ instead of /issues/, say:

"That's a pull request, not an issue. Want me to plan from the PR description, or is there a related issue I should look at instead?"

Wait for the user's response before continuing.

Fetch the issue:

gh issue view <number> --repo <owner/repo> --json title,body,labels,assignees,comments --jq '{title, body, labels: [.labels[].name], assignees: [.assignees[].login], comments: [.comments[] | {author: .author.login, body}]}'

If the command fails (404, auth error, private repo), show the user the error output and say:

"I couldn't fetch that issue. Please verify the issue number, repository name, and that you have access. You can check with gh auth status and gh repo view <owner/repo>."

Stop here. Do not proceed with a failed fetch.

Identify candidate linked issues:

Scan the issue body for references to other issues. These are candidates, not confirmed links — they may include false positives from headings, anchors, or unrelated mentions.

gh issue view <number> --repo <owner/repo> --json body --jq '.body' | grep -oE '(#[0-9]+|https://github\.com/[^/]+/[^/]+/issues/[0-9]+)' | sort -u

Store these candidates for Step 5, where the user will confirm which are actually relevant.

Step 2 — Read the Codebase

From the project root, build a working understanding of the codebase:

1. Directory structure — Read the top-level layout. Identify source directories, test directories, config files, and entry points.
2. Key files — Based on the issue context, identify the files most likely to be involved. Read them.
3. Recent commits — Check the last 10-15 commits on the current branch for relevant context:

git log --oneline -15

4. Test patterns — Find an existing test file to understand the project's testing conventions (framework, file naming, directory structure).

The goal is to know where the issue's changes will land — not to memorize every file. If the codebase is large, focus on the areas the issue describes. If you're unsure where changes land, flag this in Step 3 and ask the user.

Step 3 — State Understanding

Present your understanding to the user. This is a checkpoint — they correct you here before you go deeper.

Format your response as:

What I understand the issue is asking for: [Your interpretation in your own words — do not copy-paste the issue body]

Where I think the changes will land:

• path/to/file.ext — [what changes here and why]
• path/to/other.ext — [what changes here and why]

Acceptance criteria (as I understand them):

1. [Criterion]
2. [Criterion]
3. [Criterion]

[If criteria are unclear:] Note: The issue doesn't have explicit acceptance criteria. The above is my best interpretation — let me know what I'm missing.

Wait for the user to confirm or correct before proceeding.

Step 4 — Ask Clarifying Questions

Ask questions one at a time. Each question should target a specific gap that would cause ambiguity in the plan — unclear acceptance criteria, ambiguous scope, missing context about why something is the way it is, or behavioral details that aren't specified.

Guidelines:

• One question per message. Wait for the answer before asking the next.
• Prefer multiple choice when the options are known. Open-ended is fine when they're not.
• Stop when you are confident you can produce a plan that another Claude session could execute without asking its own clarifying questions.
• If you've asked 5+ questions, you should be close to confident. If you're not, tell the user what's still unclear and ask if they can fill the remaining gaps in one shot.

Do not ask questions that:

• Are answered by the issue body you already read
• Are answered by the codebase you already read
• Are about implementation details you can decide yourself (e.g., variable names, function signatures)

Step 5 — Check Linked Issues

If no candidate linked issues were found in Step 1, skip this step entirely. Do not mention it.

If candidates exist, fetch each one:

gh issue view <number> --repo <owner/repo> --json title,body --jq '{title, body}'

Present a summary to the user:

I found these linked issues:

• #101 — [Title]: [One-sentence summary of what it's about]
• #102 — [Title]: [One-sentence summary of what it's about]

Which of these (if any) should I factor into the plan?

Only incorporate the issues the user selects. For selected issues, note their context in the plan's "Linked Context" section.

Step 6 — Produce the Plan

Generate the plan using references/plan-template.md as the structural guide. Fill every section with concrete content from Steps 1-5.

Conditional sections:

• If no linked issues were incorporated, omit the "Linked Context" section entirely from the output.
• Determine the issue type from labels (e.g., bug, enhancement, feature). If no label maps to a type, use "Task" as the default.

Implementation steps must be:

• Numbered and ordered logically (dependencies first, then consumers, then tests)
• Function-level: each step names the file, the function/method, and exactly what to do
• Each step has a "Verify" line explaining how to confirm it worked
• Specific enough that another Claude session can execute them without asking clarifying questions

Ask where to save:

"Where should I save the plan? Default: plans/<issue-number>-<slug>.md (e.g., plans/42-fix-token-refresh.md)"

Write the plan to the user's chosen path (or the default if they accept it). If the plans/ directory doesn't exist, create it.

After saving, tell the user:

"Plan saved to <path>. You can hand this file to a new Claude session to execute."