--- name: incremental-planning description: >- Incremental planning workflow that replaces native plan mode with issue tracking integration (GH issues, Jira cards). Use when Claude tries to enter plan mode (EnterPlanMode is denied by hook), when asked to "plan", "design an approach", "how should we implement", or before any multi-file implementation task. Asks clarifying questions first, writes plan to file incrementally with file structure mapping, BUGS.md cross-referencing (sets Tracked In for overlapping bug entries), per-task quality review (sonnet subagent), tiered breakpoints for scope vs detail ambiguity, and assumption surfacing in Phase 6. Provides research context and summaries in chat for feedback. Never displays full plan content in chat. allowed-tools: Read Write Edit Agent Bash AskUserQuestion LSP Skill ToolSearch --- # Incremental Planning > **Note:** `{skill_dir}` refers to the absolute "Skill directory" path provided in your system instructions. Replaces native plan mode with a question-first, file-based, incremental workflow. The plan lives in a file. Chat contains research, questions, and summaries — never full plan content. ## Activation This skill activates when: - `EnterPlanMode` is denied by the tool-selection-guard hook (message includes "incremental-planning") - User asks to "plan", "design", "how should we build", "let's think about how to implement" - You're about to start a multi-file implementation task **Announce at start:** "Using incremental-planning to design the approach." ## Core Rules 1. **Research and context go in chat.** Share what you find, your reasoning, and your questions directly in conversational output. The user needs this context to give informed answers. 2. **Plan content goes to file.** Write plan sections to the plan file using Write/Edit tools. Provide 1-2 sentence summaries in chat after each section. 3. **Never dump plan content into chat.** If the user wants to read the plan, tell them the file path. Only paste specific sections if the user explicitly asks to see them. 4. **Questions before writing.** Do not write ANY plan content until Phase 2 is complete. 5. **Incremental writing.** Write one section/task at a time, never the whole plan at once. ## Phase 0: Assess Before starting the full workflow, classify the task domain and assess planning depth. ### Cynefin Classification Classify the task using this decision tree: ``` Are there documented best practices that clearly apply, and any competent engineer would reach the same answer? YES → Clear: Apply best practice. Straightforward execution. Is the situation in active failure/crisis mode requiring immediate action? YES → Chaotic: Stabilize first. Defer analysis. Do you have enough information to define the problem space at all? NO → Disorder: Gather information first. Probe as Complex. Can expert analysis determine the correct approach (even if multiple valid approaches exist)? YES → Complicated: Full analysis. Expert decomposition. Are outcomes uncertain even after analysis? Does the solution space feel unbounded, or do experts disagree on whether the problem is solvable as stated? YES → Complex: Probe design. Smaller iterations. More checkpoints. ``` **Domain summaries:** - **Clear** — Known cause→effect. Best practice exists. No meaningful uncertainty. - **Complicated** — Discoverable through analysis. Multiple valid approaches, one best answer. - **Complex** — Cause→effect only visible in retrospect. Emergent behavior. Probe first. - **Chaotic** — No discernible pattern. Stabilize immediately. Analyze after. - **Disorder** — Unknown which domain applies. Probe as Complex until classified. **Chat output (required):** > "Cynefin domain: [X]. Justification: [one sentence explaining the classification]." Classification feeds into depth assessment below but does not override it. If Phase 1 exploration reveals the task belongs to a different domain, update the classification and state it explicitly: "Reclassifying to [domain] because [reason]." ### Depth Assessment **Decision matrix:** | Signal | Action | |--------|--------| | Single file, clear requirement | Skip planning. Just do the work. | | Multi-file, clear requirements | Light planning: 1-2 questions in Phase 2, skip Phase 3 | | Multi-file, unclear requirements | Full planning: all phases | | Architecture or design change | Full planning + Phase 3 expert consultation | **Chat output:** > "This touches [areas] and involves [scope]. I'll do [full/light] planning." The user can override your assessment. ## Phase 1: Explore Gather context before asking questions. You need to understand the landscape to ask informed, specific questions — not generic ones. ### Actions - Launch an **Explore agent** (`Agent` with `subagent_type: "general-purpose"`) for relevant codebase areas - Read `PROJECT.md` from the memory directory (detect using `[{skill_dir}/../../references/project-memory-reference.md](../../references/project-memory-reference.md)` Directory Detection section) for past architectural decisions - Read `LESSONS.md` (if exists, structured per `[{skill_dir}/references/lessons-template.md](./references/lessons-template.md)`) from the memory directory for relevant past lessons. Silently incorporate applicable lessons — especially Architecture and Planning categories — into your approach without announcing each one. Do not quote lessons verbatim in chat. - Check `{memory_dir}/BUGS.md` (if it exists) for open bug entries whose `### Files Involved` paths overlap with the areas being planned. Note any overlaps — these inform Phase 4 (section 2.5. BUGS.md Cross-Reference). - Search **claude-mem** MCP for relevant past work, decisions, and learnings - Use **Serena** MCP `get_symbols_overview` for component-level understanding (if applicable) - Use **sequential-thinking** MCP to reason about scope boundaries - **Discover documentation surfaces** — Use the detection patterns in `[{skill_dir}/../../references/documentation-taxonomy.md](../../references/documentation-taxonomy.md)` (Documentation Surfaces section) to find all surfaces in the project. Note which exist and what they document. This inventory feeds Phase 4 and Phase 5. - **Evaluate external research need** — If the task description or user request names a third-party library, framework, or service not already present in the codebase, invoke `/deep-research` (via the `Skill` tool) in External mode before proceeding to Phase 2. If the task involves evaluating how the current codebase uses an existing third-party component, invoke `/deep-research` (via the `Skill` tool) in Bridged mode. Feed the research findings into Phase 2 questions as informed context. ### Chat Output Share your findings in full. The user needs this context to answer Phase 2 questions accurately. This is NOT a summary — include specific files, patterns, past decisions, and anything relevant (see the Phase 1 & Phase 3 chat output examples in `[{skill_dir}/references/plan-format.md](./references/plan-format.md)`). ## Phase 2: Clarify Ask targeted questions using the `AskUserQuestion` tool. Questions must be informed by Phase 1 findings — reference specific code, files, and past decisions. ### Hard Gate **You MUST ask at least 3 rounds of `AskUserQuestion` and receive answers before writing ANY plan content to a file. No exceptions.** "Simple" tasks are where unexamined assumptions cause the most wasted work. If the task is truly simple, the questions will be quick to answer. ### Tracker Question After the Hard Gate minimum of 3 clarification rounds is satisfied — as the final question before the Exit Condition check — ask the user about issue tracking via `AskUserQuestion`. This question does NOT count toward the 3-round minimum. For light planning (1-2 questions), ask the Tracker Question after the clarification questions are complete, regardless of round count. Present these 5 options: 1. **Create GitHub issue** — "Create a new GH issue in the detected repo with an issue summary" 2. **Link existing GitHub issue** — "Link to an existing GH issue by number (e.g., #42)" 3. **Create Jira card** — "Create a new Jira card via the jira-agent with an issue summary" 4. **Link existing Jira card** — "Link to an existing Jira card by key (e.g., PROJ-123)" 5. **None** — "No external issue tracking for this plan" If the user selects "Link existing" for either GH or Jira, follow up with an `AskUserQuestion` asking for the issue number/key. ### Workflow Question After the Tracker Question, detect the project's workflow mode. This question does NOT count toward the 3-round minimum. 1. Check WORK_ETHIC.md for `**Workflow:**` field 2. Check project CLAUDE.md for `## Workflow` section 3. If found and set to `incremental`, inform the user: "Detected incremental workflow mode. I'll add PR boundary markers to the plan." 4. If not found or set to `fast`, inform the user: "Using fast workflow (no PR boundaries). You can override this by setting `**Workflow:** incremental` in your WORK_ETHIC.md, or adding a `## Workflow` section with `mode: incremental` to your project CLAUDE.md." 5. Allow the user to override via `AskUserQuestion` if they want to change the detected mode for this specific plan. ### Exit Condition You can proceed to Phase 3 (or Phase 4 directly for light planning) when you can articulate ALL of: 1. **Scope** — what the user wants built 2. **Behavior** — how it should work 3. **Constraints** — technical, security, compatibility requirements 4. **Non-scope** — what's explicitly out of scope If you can't articulate all four, ask another question. ### Non-Scope Validation Before finalizing the Non-scope section, verify each item is genuinely unrelated to the user's stated goals. Items that address the user's goals but are labeled as "future version," "v2," or "next iteration" are scope reduction, not scope management — move them into the task list or present them to the user as an explicit scope question via `AskUserQuestion`. The model does not decide what is in scope. If prioritization is needed, present options: "This plan could include [X] (adds ~N tasks) or defer it. Which do you prefer?" Do not silently exclude work by relabeling it as out of scope. ### Question Design - Use `AskUserQuestion` with structured options when possible (easier to answer) - Include research context WITH each question — don't make the user remember Phase 1 findings - One primary question per `AskUserQuestion` call - Question categories: **Scope** (multi-select), **Approach** (single-select), **Constraints** (open-ended ok), **Priority** (single-select) ### Anti-Pattern: Proposing Approaches Too Early Do NOT propose "2-3 approaches" during clarification. That's the brainstorming skill's pattern. Here, the approach **emerges from answers**. Ask about requirements, not solutions. Bad: "I see two approaches: A or B. Which do you prefer?" Good: "Should sessions replace JWT for web clients, or coexist alongside JWT?" The difference: the first imposes Claude's framing. The second discovers the user's intent. ## Phase 3: Consult (Conditional) **Only for complex tasks** (architecture changes, security-sensitive work, major features). Skip this phase for light planning. Launch specialized agents in parallel using the `Agent` tool: - **`code-quality:architect`** — "Given [Phase 1 context] and [Phase 2 requirements], what are the key architectural considerations?" - **`code-quality:security`** — "Review these requirements for security implications" (only if auth, data, or API work) - **`code-quality:qa`** — "What testing approach covers these requirements?" (only if test strategy is non-obvious) - **`/deep-research`** (via `Skill` tool, not `Agent`) — "Research [specific technology/pattern question] to inform the plan" (invoke when Phase 1 identified a named third-party technology and Phase 2 answers did not resolve the technology choice) Present findings and decision points directly in chat. Use `AskUserQuestion` for decisions that came out of expert review (see `[{skill_dir}/references/plan-format.md](./references/plan-format.md)`). ## Phase 4: Write Incrementally Now write the plan. One section at a time. ### Determine Plan File Location Before creating the plan file, check where it belongs: 1. Detect the project memory directory using the convention in `[{skill_dir}/../../references/project-memory-reference.md](../../references/project-memory-reference.md)` (Directory Detection and Worktree Resolution sections). 2. **If found:** Generate a run ID per the Run-ID Naming Convention in that reference, then create the plan at `{memory_dir}/plans/{run-id}-.md` (create the `plans/` subdirectory if it doesn't exist) 3. **If none found:** Fall back to `~/.claude/plans/{run-id}-.md` (create `~/.claude/plans/` if it doesn't exist) **Do NOT create a `hack/` directory if one doesn't exist.** That's a project-level decision. Announce the location: "Plan file: `hack/plans/feat-auth-1711388400-session-auth.md`" ### Writing Sequence Follow `[{skill_dir}/references/plan-format.md](./references/plan-format.md)` for the full header field specifications, `## File Structure` table layout, `2.5. BUGS.md Cross-Reference` procedure, and `## Task N` template. #### 1. Write the Header Write the plan header with `**Field:**` bold fields (`**Goal:**`, `**Cynefin Domain:**`, `**Domain Justification:**`, `**Architecture Summary:**`, `**Tech Stack:**`, `**Key Decisions:**`, `**Branch:**`, `**Tracker:**` per `[{skill_dir}/../../references/tracker-field-spec.md](../../references/tracker-field-spec.md)`, plus full-planning sections for `**Documentation Impact**` per `[{skill_dir}/../../references/documentation-taxonomy.md](../../references/documentation-taxonomy.md)`, `**Options Considered**`, `**Trade-offs Accepted**`, `**Security Flags**`, and `**Open Questions**` — see `[{skill_dir}/references/plan-format.md](./references/plan-format.md)`): - **Iterations:** — Initialize all 5 lifecycle counters at 0 when the plan is created (both light and full planning): ``` **Iterations:** - review-cycle: 0 - fix-cycle: 0 - pr-review-cycle: 0 - pr-fix-cycle: 0 - quality-gate: 0 ``` - **Workflow:** — `fast` (default) or `incremental` (precedence: Phase 2 override → `WORK_ETHIC.md` → `CLAUDE.md` → `fast`). - **PR Boundaries:** — (only when `**Workflow:** incremental`) Task-to-PR mapping (`PR 1: Tasks 1-3, PR 2: Tasks 4-6`), finalized in Phase 5. Internal labels (`PR 1`, `PR 2`) are plan-file plumbing only — they must NOT appear in PR titles, PR bodies, or user-facing messages. - **PRs:** — (only when `**Workflow:** incremental`) Tracks created PR numbers (`PR 1: pending, PR 2: pending`). **Chat output:** "Wrote plan header. Goal: [1 sentence]. Architecture: [1 sentence]." #### 2. File Structure Mapping & 2.5. BUGS.md Cross-Reference Write the `## File Structure` section (`### Files to Modify`, `### Files to Create`, `### File Design Notes`) per `[{skill_dir}/references/plan-format.md](./references/plan-format.md)`. Then check `{memory_dir}/BUGS.md` for open entries (`Investigating`, `Root Cause Found`, `Fix Ready`) whose `### Files Involved` paths match the plan's files by exact file match (after stripping `:NN`) or a common directory prefix of at least 3 components. If `**Tracked In:**` is `—` (or missing), update it to `Plan: plans/{plan-filename}.md`. #### 3. Write Each Task Append one task at a time (`## Task N: [Short Title]`) with `**Files:**`, `**Depends on:**`, optional `**PR:**`, checkbox steps (`- [ ] **Step 1:** ...` with `Test:` command), `**Documentation updates:**`, and `**Commit:**` per `[{skill_dir}/references/plan-format.md](./references/plan-format.md)`. **Chat output per task:** "Task N written: [1 sentence description]. N steps." **After writing each task (full planning only — skip for light plans):** Dispatch a reviewer subagent. Read the template at `[{skill_dir}/references/task-reviewer-prompt.md](./references/task-reviewer-prompt.md)`, fill in the placeholders (`{PLAN_FILE_PATH}`, `{TASK_NUMBER}`, `{PRIOR_TASK_SUMMARIES}`), and pass the result as the prompt: ``` Agent( description="Review plan Task N", model="sonnet", prompt=