create-plan

name	create-plan
description	Create detailed implementation plans through interactive research and iteration. Use when starting a new feature, refactoring, or complex task that needs careful planning before implementation.
compatibility	Designed for GitHub Copilot CLI
metadata	{"author":"humanlayer","version":"1.0","original-source":"https://github.com/humanlayer/humanlayer"}

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, 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.

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, research documents, related implementation plans
   • Any JSON/data files mentioned
   • Use the view tool to read entire files
   • CRITICAL: DO NOT spawn sub-tasks before reading these files yourself

2. Spawn initial research tasks to gather context: Before asking the user any questions, use the task tool with explore agent type to research in parallel:

   • Find all files related to the ticket/task
   • Understand how the current implementation works
   • Find any existing documentation about this feature

3. Read all files identified by research tasks:

   • After research tasks complete, read ALL files they identified as relevant
   • 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

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]
   

Step 2: Research & Discovery

After getting initial clarifications:

1. If the user corrects any misunderstanding:

   • 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 update_todo to track exploration tasks

3. Spawn parallel sub-tasks for comprehensive research: Use the task tool with appropriate agent types:

   • explore - To find files, understand implementations, find patterns
   • codebase-analyzer - For deeper analysis of specific components (if available)

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, write the plan using this template:

# [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:
- [ ] Tests pass: `npm test` or `make test`
- [ ] Type checking passes: `npm run typecheck`
- [ ] Linting passes: `npm run lint`

#### Manual Verification:
- [ ] Feature works as expected when tested via UI
- [ ] No regressions in related features

**Implementation Note**: After completing this phase and all automated verification passes, pause for manual confirmation before proceeding to the next phase.

---

## Phase 2: [Descriptive Name]
[Similar structure...]

---

## Testing Strategy

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

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

## References
- [Related files or documentation]

Step 5: Review and Iterate

1. Present the draft plan:

   I've created the implementation plan.
   
   Please review it and let me know:
   - Are the phases properly scoped?
   - Are the success criteria specific enough?
   - Any technical details that need adjustment?
   - Missing edge cases or considerations?
   

2. Iterate based on feedback until the user is satisfied

Important Guidelines

1. Be Skeptical: Don't assume - verify through research
2. Think Deeply: Consider edge cases, integration points, and failures
3. Be Specific: Include file paths and line numbers
4. Maintain Quality: Plans should be actionable and verifiable
5. Focus on Value: Prioritize user-facing improvements
6. Iterate Willingly: Plans improve through collaboration