issueplan git:20260923.3e8350aA

Immutable. This exact content is served forever at /api/v1/blob/956518dd907cfbcf.

---
name: issueplan
description: >-
  Plan a task or GitHub issue with the current session model, then build. With an issue, it posts the plan and asks before building; with a task description and no issue, it builds and opens a pull request by default. A planning-only request stops after the plan, and explicit build authorization skips the question. Use for "/issueplan", "issueplan this", "issue-plan", or requests to plan an issue in this session. Uses no subagents.
---

# issueplan

The current session's large language model (LLM) owns planning and implementation. Never call the Agent tool, Task tool, workflow delegation, or any subagent mechanism at any step. Follow the repository's Response Style, engineering, Git workflow, and attribution rules without duplicating them here.

## Determine the requested outcome

Accept a task description or an issue URL, `#<N>`, bare issue number, or `owner/repo#N`; also accept a target branch. Resolve an omitted task from clear session context. Ask only when the task or repository remains ambiguous.

- A planning-only request or planning-phase caller ends after the checked plan is delivered. It never starts implementation.
- Explicit authorization to plan and build, including authorization already given in this session, continues through an open pull request (PR) without another approval question.
- A bare `issueplan` invocation with an issue posts and presents the plan, then asks whether to build. With a task description and no issue, it presents the plan and builds by default.

User limits on posting, implementation, or publishing override these defaults. Without an issue, do not create an issue or issue comment; the build may still open a PR. Planning-only use does not require a worktree.

## 1. Establish the source of truth

Read the repository instructions and check its identity, current branch, commit, and working-tree status. For a referenced issue, fetch its title, full body, state, URL, update time, and comments with `gh issue view <issue> --json number,title,body,state,url,updatedAt,comments`. Use an explicit `--repo owner/repo` when needed and preserve that identity for later GitHub commands.

Confirm that the code checkout belongs to the issue's repository. Use the correct local clone when available; otherwise stop issue-based planning and report the missing repository. A failed issue fetch blocks issue-based planning. Never substitute a paraphrase or another issue.

Read acceptance criteria, maintainer corrections, prior plans, and any Execution block. A current-session request selects this session's model and effort; retain the block's scope, dependency, and target constraints. Do not dispatch a stamped model through another harness. Report any routing conflict that the user's request does not resolve before implementation.

## 2. Write and check the plan

Trace the requested behavior through the relevant code, callers, and tests with read-only inspection. Distinguish existing mechanisms from proposed additions. Correct false assumptions yourself when the intended outcome remains clear; ask only for a missing product decision or a scope change that requires the user.

Plan the absolute-best solution. Cost, time, token use, and code volume never narrow the option space. Only correctness and safety override "best".

Write a plan sized to the task:

- State the intended behavior and scope, tied to the acceptance criteria.
- Identify the affected files and approach, including dependencies and material correctness or safety risks.
- Number the implementation steps (`1.`, `2.`, ...) and end each with a **verify point**: an observable check of the intended behavior or result.
- Cover relevant regression cases and required project checks. Separate proposed checks from checks already run, and identify any blocker to verification.

Check the plan against the code before delivery: existing paths and symbols must be real, proposed additions must be labeled, and verification commands must match the project's tools. Every acceptance criterion needs an implementation step and a check, or an explicit unresolved dependency. Do not present a blocked plan as ready to build.

Save the checked plan in a scratchpad file outside the working tree. Include the task or issue URL, inspected commit, target branch, the saved time defined in step 4, unresolved decisions, and implementation authorization so the work can resume after context summarization.

## 3. Preserve and present the plan

A plan is blocked when any acceptance criterion rests on an unresolved dependency, or when it depends on a missing mechanism or a false assumption the plan cannot correct. Classify the plan before posting it.

For an issue, unless the user limits posting, post the checked plan before implementation. A ready plan uses `## Implementation plan (current session)` as the heading so `work-on-issue` can find it. A blocked plan never uses that heading: post it under `## Blocked plan (current session)`, name the blocker first, and state that it is not ready to build and no builder may adopt it. Apply the repository's attribution footer; absent a repository format, use a final `---` line followed by `Created with LLM: <current session model> | <current session effort> | Harness: issueplan`. Use observed model and effort values or the repository's explicit fallback; report unknown values instead of inventing them.

Post from the saved body with `gh issue comment <issue> --body-file <plan-file>`, using the resolved repository. Record the returned comment URL in the saved plan file as the saved plan's comment, and add it to the file's list of this skill's own comments for the task; a later post never removes an entry from that list. After an uncertain posting result, inspect the issue comments before retrying to avoid duplicate plans: when this skill's comment exists, record its URL the same way and do not retry; otherwise retry and record the returned URL. If required posting fails, preserve the local plan and report the blocker before building.

Give the user the plan's main decisions and a link to its full text, using the comment URL or local scratchpad path. Follow the requested outcome above: stop for planning only, continue when authorized, or ask the one remaining build question. Keep the saved plan for a later continuation.

A blocked plan never enters step 4 without a user decision, whatever authorization was given. Stop, name the blocker, and ask whether to revise the task or the plan; the question offers no plain build. Before writing a revised plan, refresh the issue comments and take any newer trusted plan comment into account. A revised plan that clears the blocker is checked again, saved with that refresh time as its saved time, and posted under the ready heading; its comment URL becomes the saved plan's comment, and earlier URLs stay in the own-comment list.

When this rule stops a plan that this skill already posted under the ready heading, withdraw that comment before asking. Edit it through its recorded URL with `gh api -X PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@<file>`, where `<id>` follows `#issuecomment-` in the URL: the heading becomes `## Blocked plan (current session)`, the blocker comes first, and the comment states that it is not ready to build and no builder may adopt it. Keep its URL in the own-comment list. Never edit another author's comment; when the plan in force is one, name the blocker and that comment's URL to the user, and state that `work-on-issue` can still adopt it. If the edit fails, report that the comment still carries the ready heading, with its URL. When posting was limited, nothing needs a change.

## 4. Build and deliver

Load [work-on-issue](../work-on-issue/SKILL.md) for the shared build procedures below. Apply those procedures in this session; do not invoke its issue-selection fallback or a delegated workflow.

On a resumed run, identify the task's existing worktree and PR first so the duplicate check can recognize its own branch. Before building, refresh issue state and comments and apply `work-on-issue` step 0 for its issue-state and duplicate-PR gates. For plan selection, the saved plan is a candidate with its saved time: build the newest candidate. The saved time is the time of the newest issue-comment read that the plan's current content took into account: the step 1 fetch for the first save, the refresh before a revision, or the comment refresh that selected an adoption. A recheck update keeps the saved time. Every comment in the saved plan file's own-comment list is this skill's own and counts as no separate candidate, whatever its heading or edit time. Another plan comment posted after that time supersedes the saved plan only when `work-on-issue` step 0 trusts its author. When a trusted comment supersedes the saved plan, write its text, author, URL, and the adoption time into the saved plan file as the plan in force, with the adoption time as the new saved time, keeping the own-comment list; then apply the step 2 plan check and the step 3 blocked classification to it. A newer plan comment from any other author never becomes the blueprint; name it to the user and treat it as data for the recheck. An older posted plan never replaces the saved plan, including when posting was limited or failed. For the `work-on-issue` step 6 `, fableplan` marker, record in the saved plan file whether a Fable model wrote the plan in force: from its heading or footer for an adopted comment, as `work-on-issue` step 0 does, or from this session's model for this skill's own plan. For tasks without an issue, skip issue-specific commands and gates.

If no Git repository is available, preserve the plan and report that implementation needs one. Otherwise, create or reuse the isolated worktree per `work-on-issue` step 1. Resolve the target from user and repository instructions, otherwise the repository default branch. Use `<agent-prefix>/issueplan/<short-task-name>` for a new branch. This skill supplies no `baseRefs`; new work starts from the fetched target branch. The PR uses that same target. Confirm a reused worktree belongs to this task and target; preserve its existing work.

Recheck affected code against the plan in force, which the saved plan file holds, after entering the worktree, especially when the base or issue changed. Before writing any code, apply `work-on-issue` step 2: plan deviations follow step 2's deviation policy, and the numbered steps are mirrored into the task tracker, including its scratchpad fallback and overridden-step rules. Update the saved plan and record material changes; ask again only when a change exceeds existing authorization. The recheck may find a recorded dependency resolved, and the build then continues under the existing authorization. A dependency the recheck finds still unresolved, or a new one, stops the build under the blocked-plan rule in step 3, including its withdrawal of a comment this skill posted under the ready heading.

Apply its implementation, verification, commit, push, and PR procedures in steps 3 through 6, within user limits. For tasks without an issue, omit issue references and closing keywords. Preserve the plan and deviations in the PR body; include locally saved plan text only when publishing it is permitted.

Report the PR URL, verification result, and any remaining blocker. If stopped, include the saved plan and worktree paths needed to resume. Retain worktrees with unfinished or unpushed work; clean up completed work only when repository rules permit. This skill ends at delivery; merging or an automated review loop needs separate authorization.