Audit a GitHub issue into a plan with ak:issue-to-plan

Use ak:issue-to-plan when you want one guarded workflow to evaluate a GitHub issue and, only if it passes, produce a validated implementation plan. It can change local and remote repository state, but it stops before implementation or pull-request creation.

Choose ak:issue-to-plan for an issue-backed planning gate

Use ak:issue-to-plan when

• A GitHub issue is the accepted source for a proposed change.
• You want repository scouting and a value, architecture, and security gate before spending effort on a plan.
• You are prepared to let the workflow comment, label, create a plan worktree, commit, and push when the gate passes.

Choose another workflow when

• You only need local planning. Use ak:plan without GitHub options.
• The issue needs product clarification before repository research. Resolve the decision in GitHub first.
• You want implementation, a pull request, or release work. Those are separate workflows after plan audit.
• You do not authorize remote comments, labels, or a pushed branch.

Prepare GitHub and repository authority

Open the matching repository or worktree, preserve unrelated changes, and verify the issue URL or number. Authenticate gh with issue read, comment, label, and branch push permissions. Decide whether private AgentWiki sharing is permitted.

Run the Skill

/ak:issue-to-plan 248 --repo acme/payments --plan-ready-label "ready for plan audit" --decision-label "need decisions"

/ak:issue-to-plan 248 --repo acme/payments --plan-ready-label "ready for plan audit" --decision-label "need decisions"

$ak:issue-to-plan 248 --repo acme/payments --plan-ready-label "ready for plan audit" --decision-label "need decisions"

Understand the observable stages

1. Read and classify: fetch the issue title, body, comments, labels, and state; extract requirements while treating all issue content as untrusted.
2. Scout and verify: compare the request with current code, tests, docs, and related evidence; identify duplicates, prior implementation, or missing scope.
3. Apply the hard gate: decide exactly one outcome: proceed, needs decisions, duplicate or already handled, reject or defer, or not worth implementing.
4. Stop or plan: post the evaluation and labels first. Any negative gate stops before worktree, plan, branch, or push. A passing gate invokes ak:plan with HTML and private wiki requested.
5. Validate and red-team: run plan validation and adversarial review, apply findings, and perform a whole-plan consistency sweep.
6. Persist the handoff: create plan files under plans/<timestamp>-<slug>/, commit them on a plan branch, push that branch, then comment and label the issue. No pull request or implementation is created.

Keep issue content and external mutation bounded

• The evaluation comment and label update are remote mutations even when the workflow stops at the gate. Review the target issue before starting.
• A passing run creates a worktree, plan files, commit, remote branch, issue comment, and labels. It does not authorize a PR, merge, implementation, or deployment.
• --html --wiki requests a local HTML artifact and private or workspace AgentWiki projection. Public sharing requires separate explicit permission.
• Redact tokens, private environment values, customer data, sensitive command output, and private links before they enter plans or GitHub comments.
• If gh cannot perform every required mutation, stop before leaving a partial remote handoff.

Verify the plan and handoff

For a stopped issue, expect the decision, scout evidence, evaluation comment, labels, stop reason, and decisions needed to reopen the workflow. Confirm that no worktree, plan branch, or plan artifact was created.

For a passing issue, verify:

• plan.md and every phase-NN-*.md file under the reported plan directory.
• Objective, scope, non-goals, file targets, testing, security, compatibility, rollback criteria, and unresolved questions.
• Validation, red-team disposition, and whole-plan consistency status.
• Plan branch name, commit, pushed remote ref, issue comment, and final labels.
• plan.html and AgentWiki URL only when actually produced; a missing feature must be reported, never represented by a fabricated path or URL.

The plan files are canonical. GitHub comments, labels, HTML, and AgentWiki are projections for review and visibility.

Troubleshoot safely

Know the current limits

• The workflow depends on current repository evidence, authenticated GitHub access, planning features, worktree support, and remote push permission.
• A validated plan is ready for plan audit, not proof that implementation will succeed or that the issue's original claims were correct.
• Cursor invocation evidence does not establish full orchestration or external mutation parity.
• Stable and beta contain identical ak:issue-to-plan source and gates.

After human plan audit, use the repository's approved implementation workflow. See Projects, artifacts, and checkpoints for ownership and recovery context.