# Create Plan

> Create detailed implementation plans through interactive research and iteration

- Skill: `brianevanmiller/create-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add brianevanmiller/create-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/brianevanmiller/create-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: brianevanmiller (https://skillmd.com/u/brianevanmiller)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/brianevanmiller/create-plan

---


# 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 skill is invoked:

1. **Check if parameters were provided**:
   - If a file path or ticket reference was provided as a parameter, skip the default message
   - Immediately read any provided files FULLY
   - Begin the research process

2. **If no parameters provided**, 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 skill with a ticket file directly: `/create_plan thoughts/allison/tickets/eng_1234.md`
For deeper analysis, try: `/create_plan think deeply about thoughts/allison/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/allison/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**:
   Before asking the user any questions, use specialized agents to research in parallel:

   - Use a codebase locator agent to find all files related to the ticket/task
   - Use a codebase analyzer agent to understand how the current implementation works
   - If relevant, use a thoughts locator agent to find any existing thoughts documents about this feature
   - If a Linear ticket is mentioned, use a linear ticket reader agent to get full details

   These agents will:
   - Find relevant source files, configs, and tests
   - Identify the specific directories to focus on (e.g., if WUI is mentioned, they'll focus on `humanlayer-wui/`)
   - 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 and focused 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]

   Questions that my research couldn't answer:
   - [Specific technical question that requires human judgment]
   - [Business logic clarification]
   - [Design preference that affects implementation]
   ```

   Only ask questions that you genuinely cannot answer through code investigation.

### Step 2: Research & Discovery

After getting initial clarifications:

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 a todo mechanism to track exploration tasks

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

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

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

   **For related tickets:**
   - Linear searcher - To find similar issues or past implementations

   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 findings and design options**:
   ```
   Based on my research, here's what I found:

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

   **Design Options:**
   1. [Option A] - [pros/cons]
   2. [Option B] - [pros/cons]

   **Open Questions:**
   - [Technical uncertainty]
   - [Design decision needed]

   Which approach aligns best with your vision?
   ```

### Step 3: 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 4: Detailed Plan Writing

After structure approval:

1. **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-tracking.md`
     - Without ticket: `2025-01-08-improve-error-handling.md`
2. **Use this template structure**:

````markdown
# [Feature/Task Name] Implementation Plan

## Overview

[Brief description of what we're implementing and why]

## Current State Analysis

[What exists now, what's missing, key constraints discovered]

## Desired End State

[A Specification of the desired end state after this plan is complete, and how to verify it]

### Key Discoveries:
- [Important finding with file:line reference]
- [Pattern to follow]
- [Constraint to work within]

## What We're NOT Doing

[Explicitly list out-of-scope items to prevent scope creep]

## Implementation Approach

[High-level strategy and reasoning]

## Phase 1: [Descriptive Name]

### Overview
[What this phase accomplishes]

### Changes Required:

#### 1. [Component/File Group]
**File**: `path/to/file.ext`
**Changes**: [Summary of changes]

```[language]
// Specific code to add/modify
```

### Success Criteria:

#### Automated Verification:
- [ ] Migration applies cleanly: `make migrate`
- [ ] Unit tests pass: `make test-component`
- [ ] Type checking passes: `npm run typecheck`
- [ ] Linting passes: `make lint`
- [ ] Integration tests pass: `make test-integration`

#### Manual Verification:
- [ ] Feature works as expected when tested via UI
- [ ] Performance is acceptable under load
- [ ] Edge case handling verified manually
- [ ] No regressions in related features

**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human that the manual testing was successful before proceeding to the next phase.

---

## Phase 2: [Descriptive Name]

[Similar structure with both automated and manual success criteria...]

---

## Testing Strategy

### Unit Tests:
- [What to test]
- [Key edge cases]

### Integration Tests:
- [End-to-end scenarios]

### Manual Testing Steps:
1. [Specific step to verify feature]
````

3. **Ensure the plan is realistic and scoped**:
   - Call out risks and unknowns explicitly
   - Identify where additional design work might be needed later
   - Avoid over-specifying areas that are better decided during implementation

4. **Review the plan with the user**:
   - Present the completed plan
   - Highlight major decisions and trade-offs
   - Ask for feedback on scope, phases, and risks
   - Be willing to adjust based on user input

### Step 5: Iteration & Refinement

1. **Incorporate user feedback**:
   - Update the plan to reflect decisions made in discussion
   - Clarify ambiguous sections
   - Remove unnecessary complexity

2. **Resolve open questions**:
   - If open questions remain, clearly mark them in the plan
   - Suggest how and when they should be resolved (e.g., before Phase 2)

3. **Finalize the plan**:
   - Ensure all sections are filled out
   - Double-check file paths and commands
   - Confirm success criteria are testable and concrete

4. **Sync the plan**:
   - Run `humanlayer thoughts sync` to sync the thoughts directory
   - Confirm the plan file path with the user

## Philosophy & Guidelines

- Plans should be **practical**, not theoretical
- Prefer clear, incremental phases over large, risky changes
- Always ground design decisions in the **current codebase reality**
- Make sure another engineer could pick up the plan and implement it without having been part of the conversation
- Be honest about unknowns and risks; plans are living documents

## When to Defer or Split Plans

- If the task is too large, propose splitting into multiple plans
- If the architecture is unclear, suggest a separate **research-first** task
- If business requirements are ambiguous, recommend clarifying tickets or specs before implementation