Station II: Plan Issue (ii-plan-issue)

This skill implements Station II (Define & Plan) of the 6-station pipeline (I–VI). It works across any project, language, or repository, bridging a GitHub issue to an airtight, executable specification and task plan (discipline from Addy Osmani's agent-skills collection).

Prime directive: the issue being planned is the star of the show. Planning machinery (skills, steps, contracts) is scaffolding — it lives in tasks/plan.md, never as the headline of the reply.

Pipeline Position

• Station: II of VI
• Previous Station: i-pick-issue (Station I — or the create-issue intake branch)
• Next Station: quick-fix (only on a Step 0C divert — which itself requires a quick-fix-labeled Tiny issue, the gate passing, and the operator's choice) or iii-build-plan auto (Build)

1. Invocation & Target Issue Discovery

Pre-flight helper: run node scripts/issue-intake.js [number] (or --json) to verify tree status, detect tech stack, inspect stale plans, and pre-fetch issue data in a single pass.

Option A: Invoked with an Issue Number (e.g. /ii-plan-issue 42)

1. Fetch Issue Details: Run gh issue view <number> --comments — title, body, labels, and all discussion comments.
2. Check tree clean first: Run git status --short --branch — if the tree is dirty stop and route to pipeline-triage before claiming or branching.
3. Claim the Issue: Run gh issue edit <number> --add-assignee @me to signal work has begun.
4. Create the feature branch: see canonical rule in Step 0B (i<number>/<slug> from the issue title, e.g. issue #69 Increase button size → i69/increase-button-size).
5. Set this issue as the primary planning target.

Option B: Invoked Without Arguments (/ii-plan-issue)

1. Fetch All Open Issues: Run gh issue list --state open --limit 50.
2. Group Logically: Identify project areas (labels or codebase architecture).
3. Recommend exactly one issue: highest-priority first (unblockers and core dependencies, then quick wins), with a one-line rationale.
4. Proceed immediately — do not pause to ask. Invoking /ii-plan-issue with no arguments is the operator's consent to auto-pick the recommended issue, claim it, and branch — a second confirmation would defeat the mode. Check tree clean (git status --short --branch, dirty → pipeline-triage), then check the starting branch: you must be on the base branch (master/main). On a feature branch — even a clean one with unpushed commits — stop and route to pipeline-triage: Step 0B branches from the current HEAD, so a new issue's branch would inherit that other work's commits. Only from the base branch: claim the recommended issue (gh issue edit <number> --add-assignee @me), create the feature branch per Step 0B (i<number>/<slug> from the issue title), and go straight to Section 2 on it. The consent covers the claim and the branch only — never a scope expansion, and the report still names which issue was auto-picked so the operator can redirect.

If gh fails (not authenticated, offline, or issue not found)

Stop the issue-dependent steps. Say in plain language exactly what failed, and ask the user for the issue number/title (or to run gh auth login). Never fabricate issue content and never plan from imagined data (do not invent content).

2. Step-by-Step Planning Protocol (strict order)

Step 0: Environment Auto-Detection & Size Classification (Right-Sizing)

1. Auto-detect stack: language, runtime, frameworks, and the test runner (pytest, vitest/jest, cargo test, go test, ...).
2. Size tier — state the tier plus a one-line rationale in the output:
   • Tiny — docs/typo/comment-level change; no code behavior change; zero ambiguity.
   • Small — one file or one function; straightforward once the code is read.
   • Standard — 2–5 files, internal module changes, a single architectural decision.
   • Large — cross-cutting changes, a new external dependency, public API or database schema change.
3. Task type — classify into one or more primary categories (combinations allowed): Code (default), Design, Debug, Performance, Security, Docs, UX / Copy, Research. Classify before planning: downstream stations (iii-build-plan, iv-review-build-and-pr) pick reviewers and test suites from this tag.

Step 0C: Quick-Fix Lane Divert (after the tier and task type, before Step 0A)

Tiny tier and the quick-fix label are both required — the label is a precondition for evaluation. Read the linked issue's current labels (gh issue view <number> --json labels); Station II must not rely on a label status carried forward from Station I.

Three outcomes:

1. Not quick-fix-labeled, any tier (whether or not it carries other labels such as ready-for-agent) → continue to Step 0A. Run no gate, print no gate text, offer no lane.
2. Labeled but not Tiny → remove the label (gh issue edit <number> --remove-label "quick-fix") and continue to Step 0A. Right-sizing here is the authority the label only guessed at: the label was wrong, and a stale one cannot mislead a later session.
3. Labeled and Tiny → run the 7-box gate in quick-fix. A Tiny issue may still be the wrong lane: right-sizing measures size, the gate measures risk. All 7 pass → tell the operator in one line that this looks like a quick fix (push straight to main, no PR, no reviews, no CodeRabbit) and ask whether to take it. They choose: yes → hand off to quick-fix with your 7-box verdict so it re-checks only size and its own diff instead of re-reading the issue, and stop this station; no, or any box fails → continue to Step 0A as normal, and if any box failed remove the label so a later session is not misled.

Three things are deliberately still not offered here, because at this point the full chain costs almost nothing: a new test required, no runnable verification command, or an undecided approach. Those are boxes 5, 6, and 7 — failing them is not a near miss.

Step 0A: Resolve Open Questions from Code & Consult CodeRabbit Plan

0. Handle stale plans before intake: The planning set is issue-scoped. Inspect the header of tasks/plan.md (Branch: ... | Issue: #...), tasks/todo.md, tasks/pr-body.md, and any root CONSTRAINTS.md whose header names a branch or issue. If any names another issue that is already merged or closed, replace the whole set wholesale for the new issue — a leftover checklist of [x] marks or a finished issue's constraints misread as this issue's progress at Station III. Reconciling produces a contradictory document. The write guard's refusal is sticky: a full re-read does NOT clear it — clear the file through the terminal (rm) and write fresh.
1. Check for CodeRabbit Plan in comments: Look at the discussion comments fetched via gh issue view <number> --comments. If a plan comment from coderabbitai exists:
   • Read it once, not twice: the comment carries the plan twice — a rendered copy first, then a byte-identical echo inside an HTML comment (<!-- <rawResChunk><planningResult> … -->). Ignore the echo; it only doubles context cost.
   • Map CodeRabbit's layout to ours: it keeps its own template (Summary / Design Choices / Implementation Steps with Phases+Tasks / Ticket Summary / Codebase Summary / File-Level Change Summary / Notes for follow-up agents). Mine those sections; do not wait for our section names to appear.
   • Extract skeleton & seams: treat its task phases, affected files, and seam pointers as scaffolding to save discovery time.
   • Resolve assumptions & drift: read its Assumptions/Risks or Design-Choice rationales. Anything it flagged as uncertain, any reference it left dangling (e.g. "Apply Assumption 1" with no Assumption 1 defined), and any contradiction it found between the issue text and the code is an open question to resolve from the code — treat it as [UNVERIFIED], never as fact.
   • Borrow test cases: note the exact test assertions and regression test files it specified for use in Step 3 (CONSTRAINTS.md) and Step 6 (tasks/plan.md).
   • Enforce simplicity (Rule 4): its suggestions are non-binding. It usually over-splits — merge its task list into 3–4 atomic tasks and drop invented abstractions or new files nothing requires.
   • Verify, don't assume (Rule 6): spot-check every file path, symbol, and line number it cites against the live codebase before adopting any of it. Issue line numbers are stale by default in an active repo; file paths and symbol names are the stable part — lock paths in the interface contract and re-derive line numbers at build time, recording each resolved location in the plan so Station III does not re-derive them.
   • A cited definition site can already be gone: an earlier merge may have replaced the literal with an import to the canonical module. Verify the literal still exists before counting a site as work — a vanished site shrinks the task, and an assumed site sends the build hunting for code that is already correct.
   • A stale plan can claim missing infrastructure that exists in broken form. When the plan says "the harness/test does not support X" or "no test covers Y", open the file before adopting the claim — the reality may be a dead implementation (a setter that never reaches its target, a parameter accepted and ignored), which changes the task from "add" to "repair" and changes the task's size.
   • Cost the intake once: record a three-line note in tasks/plan.md — what was adopted from its plan, what was rejected and why, and what stayed [UNVERIFIED] — so Stations III–V never re-read that comment.
   • Budget the fetch: a CodeRabbit plan comment routinely runs to tens of thousands of characters and overflows the terminal capture window. Fetch proactively to a scratch file (gh issue view <n> --json comments > <scratch>/i<n>-comments.json) and page the JSON with code — lossless, and cheaper than discovering truncation or re-running gh issue view, which pays the whole cost again. Write the scratch file to a path the code runner can read natively — a bash /tmp write is invisible to Windows Python in execute_code; copy it to a native path (the Hermes scratch dir) before paging.
   • Record every [UNVERIFIED] with its resolution as you verify it: when you resolve one against live code during Step 0A, write the answer into the plan intake note immediately (e.g. renderServiceHeader not in module.exports → the harness must drive state through the click handler). An unresolved list is useless to Station III; a resolved one stops it re-deriving the same answers.
   • Reject a CodeRabbit guard whose branch cannot fire on this host rather than adopting it because it looks defensive. The plan is input, not authority — a condition that is always true or always false in practice adds untested code paths and tests that cannot fail.
   • Never leave a removed symbol's name in a new comment. A comment that says "replaces the old #foo" puts the literal string #foo back into the file, so any later guard that asserts the old name is absent (assert "foo" not in html) fails on your own annotation. Describe the replacement by role ("replaces the two separate buttons"), not by the identifiers being removed.

• Planning a sub-issue: mine the parent first. A sub-issue's own text can leave its scope boundary ambiguous — its verify line may describe a state that belongs to a sibling task in the split. The parent issue's comments usually carry the operator's locked task breakdown (which task owns which move, in what order); read them before treating any child-issue statement as final scope.
• Check a new guard test's state at THIS PR's merge. A guard that scans sites a later task will move is red at this PR's merge, and CI gates on the full suite (check the repo's CI config for what the merge gate runs) — the red test blocks the merge. Resolve the three designs with the operator before locking the test's contract: land it red (owner merges by override), pin the current violations as a baseline the later tasks shrink, or pull the moves into this PR. Each choice changes what the test asserts. Record the chosen design in CONSTRAINTS.md as deliberate, not a regression, so Stations IV–V do not "fix" it.

2. Resolve Open Questions (needs-answers flag): If the issue carries the needs-answers label or an Open questions section:
   • For each open question, first try to resolve it from the code (and CodeRabbit's codebase analysis) — read the relevant paths, check how similar cases are handled in the repo.
   • Fold each resolved answer into the plan as planning input; record the resolved answers in tasks/plan.md so the reasoning survives the session.
   • Ask the operator only what is genuinely unresolvable from code — one focused batch, before Step 1. Never re-ask what the issue already answers.
   • Verify a grep-based acceptance criterion against live code before locking it. An acceptance line like "grep returns no references" is unreachable when the searched word is shared vocabulary — the same token names the retired path and a surviving unrelated mechanism (an order-book depth ladder vs. the retired strategy). Grep first: if hits survive that demonstrably are not the removed thing, the criterion can never reach zero — refine it in the plan to the enumerated symbols of the removed path and record the refinement as the acceptance bar.
3. Large or unfamiliar/legacy code: before answering, deploy the code-explorer agent persona (from this repo's agents/ directory) to trace the relevant execution paths and map the affected architecture layers; fold its findings into the plan. Persona file not found on disk → skip and record the skip — never simulate a missing reviewer persona (do not invent).

Step 0B: Confirm Feature Branch (canonical rule for Section 1)

Branch format is i<number>/<slug> from the current HEAD. Derive <slug> from the issue title: lowercase, spaces → dashes, keep only a-z 0-9 -, max 50 chars, never Hebrew — Hebrew chars are stripped, and an empty result falls back to issue-<number>. Example: issue #69 Increase button size → i69/increase-button-size; a Hebrew-only title for issue #70 → i70/issue-70. 0. Worktree first when the repo isolates issue work. When the repo's AGENTS.md names a worktree convention (e.g. .worktrees/<repo>-i<number>), create the worktree from the base branch BEFORE claiming or branching, then claim and branch inside it: git worktree add -b i<number>/<slug> <worktrees-dir>/<name> origin/<base> — the -b creates the branch inside the new tree. Never git switch -c in the main checkout first: the branch then sits checked out there, git worktree add <path> <branch> fails with 'already used by worktree', and the recovery checkout dance touches the operator's live tree. Every later station runs inside that worktree.

1. Tree was already checked clean in Section 1 — if dirty now, stop and route to pipeline-triage before branching.
2. Run git branch --show-current — if already on the issue's branch reuse it, including under the repo's own naming convention (an operator-created worktree or repo-specific format beats the canonical i<number>/<slug>; the repo's AGENTS.md outranks this skill).
3. Else if the branch exists locally or on remote (git branch --list / git ls-remote --heads origin), checkout it (git switch <branch>, fallback git checkout <branch>).
4. Else create it from HEAD (git switch -c i<number>/<slug>, fallback git checkout -b i<number>/<slug>).
5. Record the header line at the top of tasks/plan.md: Branch: i<number>/<slug> | Issue: #<number> so Stations III–V build, review, and push on the same branch.

Step 1: Domain Skill Routing

Load specialized skills that match the classified task type (and only skills that actually exist in the environment — verify before naming any skill):

Design distinction: frontend-design governs aesthetic direction, typography, and non-templated choices; frontend-ui-engineering governs accessible, responsive, production-quality UI and WCAG compliance. Execution tagging: in tasks/plan.md, every task declares its domain tag ([Design/UI], [Backend/Logic], [Debug], ...) and the verification mode iii-build-plan will run (browser preview for UI, unit/integration runner for logic).

Step 2: Specification (spec-driven-development)

• Standard / Large: create or update SPEC.md in the project root — goals, acceptance criteria, edge cases, explicit out-of-scope.
• Small / Tiny: embed a concise spec directly in the plan. No SPEC.md ceremony for small work.

Step 3: Lock Quality Guardrails (constraint-driven-development)

Create or update CONSTRAINTS.md with strict, measurable boundaries:

• Zero regressions: targeted suites covering modified files must pass; new behavior requires tests. (Full-repo sweeps stay with CI on push.)
• Performance thresholds: explicit latency/memory/runtime ceilings where applicable.
• Anti-cheat: strictly forbid skipping/disabling tests, deleting assertions, or suppressing linters.
• Dependencies: no new external dependencies without explicit approval.

Step 4: Interface Contracts (api-and-interface-design)

Lock types, data schemas, public function signatures, and communication contracts before writing business logic. Skip for Tiny/Docs tasks with no interface change.

For Standard/Large work with a non-trivial domain model, run the type-design-analyzer agent persona (from this repo's agents/ directory) over the interfaces being locked — encapsulation, invariant expression, and enforcement — before freezing the contract. Persona not found on disk → skip and record the skip.

Step 5: One Improvement Proposal (evidence-based, classified adoption)

Propose at most one concrete improvement to the issue's approach — an architectural simplification, a forgotten edge case, or a better fit to existing repo patterns.

1. Ground it in evidence: quote the motivating evidence verbatim — the exact issue text, issue comment, or code lines — not just a file/line pointer. No evidence ⇒ no proposal; never invent filler to satisfy this step; say so and skip instead (do not invent).
2. Classify the proposal:
   • Simplification / edge-case hardening → adopt-by-default: folded into tasks/plan.md after the evidence check passes.
   • Scope expansion (new behavior the issue never asked for) → opt-in only: presented as a question, enters the plan solely on explicit operator approval.
3. Rejection is recorded in tasks/plan.md with its reason, so the same proposal does not resurface next session.
4. Present the proposal in the report in one sentence so the operator can reject before build.
5. Make an opt-in question self-contained. State inside the question itself what each option concretely costs — which files move, backend vs. frontend, the review surface, what the issue's own scope boundary says. A question stripped to two labels bounces back as "explain what you mean" and costs a round trip; when it bounces, explain the dilemma in chat first, then re-ask with the costs spelled out.

Step 6: Task Decomposition (planning-and-task-breakdown)

1. Dependency graph first: before ordering anything, map which task unblocks which — a task depends on another when it needs that task's output (interface, file, data). Write the graph into tasks/plan.md as a Depends on: field per task.
2. Order risk-first: riskiest and most-uncertain tasks run early, while the cost of being wrong is still low. Size and verification follow the graph, not the other way around.
3. Size each task XS–XL: XS ≈ one-line config, S ≈ one file, M ≈ a few files, L ≈ cross-cutting, XL ≈ split it before planning proceeds.
4. Atomic vertical slices, 5–10 minutes each. Every task defines: Task ID, size (XS–XL), domain tag, target files, concise description of what is built, assigned helper skill, Depends on: (task IDs), and explicit verification method (browser check or automated test).
5. Checkpoints every 2–3 tasks: the plan declares checkpoint stops that show what works so far. In Mode A (/iii-build-plan auto) a checkpoint is a one-line progress report, not a full approval pause.
6. Map tasks to sub-issues (Standard/Large work): one sub-issue per task with native blocked-by dependency edges (see references/issue-tracker.md → Wayfinding operations), so the tracker mirrors the plan and survives the session. Tiny/Small work skips this ceremony.
7. Never overwrite the plan: if tasks/plan.md already exists for this issue (resumed work, or a previous session), reconcile — keep completed [x] marks, append new tasks, note changed assumptions at the bottom. Overwriting erases session memory (stale plans from a different, finished issue were already replaced at the start of Step 0A).
8. Save the structured plan to tasks/plan.md and the checklist to tasks/todo.md. Write todo.md for the NEW issue at the same time — a leftover checklist full of completed [x] marks from the previous issue misreads as this issue's progress at Station III.