| name | issue-plan |
| description | Read a GitHub issue and produce a posted plan of attack — gather the issue with its comments and references, survey the code it touches (read-only), author a short plan (root cause, approach, risks, test plan), then assign the issue, move it to In Progress on the board (if configured), and post the plan as the issue comment teammates read. Use when the user asks to "plan this issue", "read |
Issue Plan — from issue URL to a posted plan of attack
The output of this skill is a plan someone else could execute: the issue
comment is the public record of the approach, and it later seeds the PR
body. Write it for the teammates who will read it on GitHub, not for the
user in this chat. No code gets written or changed here — this skill is
read-only on the codebase and write-only on the issue.
Repo facts (repo, gh user, board config) come from the gh-repo-config
skill; board moves go through gh-board. Neither being configured
blocks a plan — unconfigured pieces are skipped and noted.
1. Read the issue
Accept a full URL, #N, or a bare number. Gather everything in one pass:
gh issue view <N> --json number,title,body,labels,milestone,assignees,comments,url
Read the comments too — later comments often amend or overrule the original
body. If the issue references other issues/PRs (an epic parent, a "relates
to"), skim those for constraints. If the issue is genuinely ambiguous about
what to build (not how — that's this skill's job), ask the user before
going further.
If the issue is already assigned to someone else or already In Progress on
the board, stop and ask the user before taking it over.
2. Survey the code
Before forming an opinion, survey the code the issue touches — read-only;
Explore subagents are good for this. Check the repo's CLAUDE.md/AGENTS.md
for documented gotchas (multi-tenancy, auth boundaries, basePath quirks,
dual databases, feature flags — whatever that repo calls out). The posture
is survey-first: the plan must be written well enough that someone with
zero session context could follow it.
3. Author the plan
A short plan, four parts:
- Root cause / current behavior — what the code does today and why
that's the issue.
- Approach — what will change, in which files.
- Risks / blast radius — what else touches this code, weighing the
gotchas found in the survey.
- Test plan — which checks will prove it works (commands + manual
steps), using the repo's discovered build/lint/test commands.
Write it to a uniquely-named file (issue-<N>-plan.md, never plan.md).
When implementation follows in the same session, this plan is also the seed
of the eventual PR body — write it once, well.
If the issue touches anything visible and implementation will follow,
invoke ui-evidence now — its before-captures must happen while the
code is still untouched; the "before" state stops existing the moment
implementation starts.
4. Post it (delegated housekeeping)
Spawn one subagent to do the GitHub bookkeeping — when implementation
follows, don't block on it; start implementing while it runs. Give it the
issue number, issue URL, the resolved GitHub username, the plan file path,
and (if a board is configured) the gh-board script path and board
owner/number, to run:
gh issue edit <N> --add-assignee <resolved-gh-user>
board.sh status "$ITEM" "In Progress"
gh issue comment <N> --body-file <issue-<N>-plan.md>
The comment should open with a one-line note that an AI agent is picking
this up, then the plan. Keep it factual and skimmable (headers, short
bullets) — it's how teammates see the issue being attacked.
Two delegation rules keep the posted plan honest — a subagent that can't
find the plan file will fabricate a fluent replacement, and every signal
except the content itself will report success:
- Mark the plan file as given. The prompt must say: "This file already
exists and is final — do NOT create, edit, or overwrite it; only pass its
path to the command." Anything unmarked, the subagent resolves by
improvising.
- Verify content, not exit codes. When the subagent reports back, fetch
the posted comment body
(
gh api repos/<owner>/<repo>/issues/comments/<id> -q .body) and check
it matches the plan you authored before moving on or reporting done.
Standalone judgment call: assigning, board moves, and the comment are
the default when this runs as part of a full issue workflow. If the user
asked only for a plan or an assessment ("what's the approach here?"),
deliver the plan in chat and ask before mutating the issue — posting and
self-assigning would overstep a read-only request.
Failure modes
- No project board — expected in many repos; skip the board move and
say so. Not a failure.
- Issue assigned to someone else / already In Progress — stop and ask
the user before taking it over.
- The posted comment doesn't match what you authored — the subagent
improvised. Fix it in place with
gh api -X PATCH .../issues/comments/<id> -f body=@<file> rather than
delete-and-repost — editing keeps the comment's thread position. Write
the corrected content to a new, uniquely-named file first, so you're
not racing whatever clobbered the original.
- Plan invalidated later (implementation reveals it was wrong) — post a
short follow-up comment on the issue correcting the record; don't leave a
stale plan as the last word.
