create-plan

What this skill does

<!-- SPDX-License-Identifier: Apache-2.0
     SPDX-FileCopyrightText: 2024 humanlayer Authors (original)
     SPDX-FileCopyrightText: 2025 Jorge Castro (modifications) -->

# Implementation Plan

You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.

## Initial Response

When this command is invoked:

**Input**: $ARGUMENTS

1. **Check if parameters were provided via $ARGUMENTS**:
   - If $ARGUMENTS contains a file path (e.g., `thoughts/nikey_es/tickets/eng_1234.md`), skip the default message
   - Immediately read any provided files FULLY
   - Begin the research process
   - If $ARGUMENTS contains a task description (not a file path), use it as context for planning

2. **If $ARGUMENTS is empty**, respond with:
```
I'll help you create a detailed implementation plan. Let me start by understanding what we're building.

Please provide:
1. The task/ticket description (or reference to a ticket file)
2. Any relevant context, constraints, or specific requirements
3. Links to related research or previous implementations

I'll analyze this information and work with you to create a comprehensive plan.

Tip: You can also invoke this command with a ticket file directly: `/stepwise-core:create-plan thoughts/nikey_es/tickets/eng_1234.md`
For deeper analysis, try: `/stepwise-core:create-plan think deeply about thoughts/nikey_es/tickets/eng_1234.md`
```

Then wait for the user's input.

## Process Steps

### Step 1: Context Gathering & Initial Analysis

1. **Read all mentioned files immediately and FULLY**:
   - Ticket files (e.g., `thoughts/nikey_es/tickets/eng_1234.md`)
   - Research documents
   - Related implementation plans
   - Any JSON/data files mentioned
   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
   - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context
   - **NEVER** read files partially - if a file is mentioned, read it completely

2. **Spawn initial research tasks to gather context**:
   Use specialized agents to research in parallel — do not ask the user anything yet:

   - Use the **stepwise-core:codebase-locator** agent to find all files related to the ticket/task
   - Use the **stepwise-core:codebase-analyzer** agent to understand how the current implementation works
   - If relevant, use the **stepwise-core:thoughts-locator** agent to find any existing thoughts documents about this feature

   These agents will:
   - Find relevant source files, configs, and tests
   - Identify the specific directories to focus on (e.g., if the frontend is mentioned, they'll focus on frontend/ or web/)
   - Trace data flow and key functions
   - Return detailed explanations with file:line references

3. **Read all files identified by research tasks**:
   - After research tasks complete, read ALL files they identified as relevant
   - Read them FULLY into the main context
   - This ensures you have complete understanding before proceeding

4. **Analyze and verify understanding**:
   - Cross-reference the ticket requirements with actual code
   - Identify any discrepancies or misunderstandings
   - Note assumptions that need verification
   - Determine true scope based on codebase reality

5. **Present informed understanding — no questions**:
   ```
   Based on the ticket and my research of the codebase, I understand we need to [accurate summary].

   I've found that:
   - [Current implementation detail with file:line reference]
   - [Relevant pattern or constraint discovered]
   - [Potential complexity or edge case identified]
   ```

   Do NOT list questions here. All open questions are resolved in Step 3 via grill-me.

### Step 2: Research & Discovery

After presenting the Step 1 findings (no clarifications yet — those happen in Step 3):

1. **If the user corrects any misunderstanding**:
   - DO NOT just accept the correction
   - Spawn new research tasks to verify the correct information
   - Read the specific files/directories they mention
   - Only proceed once you've verified the facts yourself

2. **Create a research todo list** using TodoWrite to track exploration tasks

3. **Spawn parallel sub-tasks for comprehensive research**:
   - Create multiple Task agents to research different aspects concurrently
   - Use the right agent for each type of research:

   **For deeper investigation:**
   - **stepwise-core:codebase-locator** - To find more specific files (e.g., "find all files that handle [specific component]")
   - **stepwise-core:codebase-analyzer** - To understand implementation details (e.g., "analyze how [system] works")
   - **stepwise-core:codebase-pattern-finder** - To find similar features we can model after

   **For historical context:**
   - **stepwise-core:thoughts-locator** - To find any research, plans, or decisions about this area
   - **stepwise-core:thoughts-analyzer** - To extract key insights from the most relevant documents

   Each agent knows how to:
   - Find the right files and code patterns
   - Identify conventions and patterns to follow
   - Look for integration points and dependencies
   - Return specific file:line references
   - Find tests and examples

3. **Wait for ALL sub-tasks to complete** before proceeding

4. **Present research findings — facts only, no invented options or questions**:
   ```
   Based on my research, here's what I found:

   **Current State:**
   - [Key discovery about existing code]
   - [Pattern or convention to follow]
   - [Constraint or dependency discovered]

   **Options mentioned in the codebase** (only if explicitly found — e.g., a features file, a comment, existing patterns):
   - [Option explicitly referenced in file:line]
   ```
   Do NOT invent design options or list pros/cons. Only surface options explicitly documented in the codebase. All design decisions happen in Step 3 via grill-me.

### Step 3: Interrogation Phase

**Do not ask questions yourself — not even one.** Use the `Skill` tool to invoke `/stepwise-core:grill-me` now.

Why: grill-me walks down the decision tree one branch at a time, with a recommended answer per question. If you ask inline, you will dump a list and lose the structured resolution that makes this valuable. Any question you feel tempted to ask here belongs inside grill-me.

Pass grill-me the full context from your research: current state, design options found, and all unresolved decisions. Let grill-me drive the conversation from there.

Only proceed to Step 4 once grill-me has resolved all open design decisions and you have shared understanding with the user on every choice.

### Step 4: Plan Structure Development

Once aligned on approach:

1. **Create initial plan outline**:
   ```
   Here's my proposed plan structure:

   ## Overview
   [1-2 sentence summary]

   ## Implementation Phases:
   1. [Phase name] - [what it accomplishes]
   2. [Phase name] - [what it accomplishes]
   3. [Phase name] - [what it accomplishes]

   Does this phasing make sense? Should I adjust the order or granularity?
   ```

2. **Get feedback on structure** before writing details

### Step 5: Detailed Plan Writing

After structure approval:

1. **Initialize thoughts directory if needed:**
   - Check if `thoughts/` directory exists
   - If it doesn't exist, use the thoughts-management Skill to initialize it:
     ```bash
     bash ${CLAUDE_PLUGIN_ROOT}/skills/thoughts-management/scripts/thoughts-init
     ```
   - This creates the complete directory structure for organizing plans

2. **Write the plan** to `thoughts/shared/plans/YYYY-MM-DD-ENG-XXXX-description.md`
   - Format: `YYYY-MM-DD-ENG-XXXX-description.md` where:
     - YYYY-MM-DD is today's date
     - ENG-XXXX is the ticket number (omit if no ticket)
     - description is a brief kebab-case description
   - Examples:
     - With ticket: `2025-01-08-ENG-1478-parent-child-