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 path as an argument, e.g. `thoughts/neil/tickets/eng_1234.md`.
For deeper analysis, add "think deeply about" before the file path.

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/neil/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 the dex:codebase-locator agent to find all files related to the ticket/task
   • Explore the codebase to understand how the current implementation works
   • If relevant, use the dex:thoughts-locator agent to find any existing thoughts documents about this feature
   • IMPORTANT: Use the dex:documentation-research-agent proactively when the task involves external libraries, frameworks, APIs, or technologies

   These agents will:

   • Find relevant source files, configs, and tests
   • Identify the specific directories to focus on
   • 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. Assess if TDD approach is appropriate: Consider whether this implementation would benefit from Test-Driven Development (TDD):

   TDD is RECOMMENDED for:

   • New features with clear expected behaviors
   • API integrations or external service connections
   • Streaming or real-time functionality
   • Complex business logic or algorithms
   • Data transformation or processing pipelines
   • Error handling or validation systems

   TDD may NOT be suitable for:

   • Simple configuration changes
   • UI/styling updates
   • Documentation updates
   • Direct bug fixes with known solutions
   • Infrastructure or deployment changes

6. Present informed understanding and ask the user for clarifications:

   First, present your understanding:

   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]
   
   **TDD Assessment:** This implementation [is/is not] well-suited for Test-Driven Development because [reasoning based on criteria above].
   

   Then, ask the user to gather answers to questions your research couldn't resolve:

   • Use structured questions with clear options when possible
   • Ask about technical decisions that require human judgment
   • Clarify business logic or requirements
   • Get design preferences that affect implementation
   • Confirm TDD approach if applicable

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

3. Spawn parallel sub-tasks for comprehensive research:

   • Create multiple research sub-agents to explore different aspects concurrently
   • Use the right agent for each type of research:

   For deeper investigation:

   • dex:codebase-locator - To find more specific files
   • Codebase exploration - To understand implementation details
   • dex:codebase-pattern-finder - To find similar features we can model after

   For historical context:

   • dex:thoughts-locator - To find any research, plans, or decisions about this area
   • dex:thoughts-analyzer - To extract key insights from the most relevant documents

   For external documentation:

   • dex:documentation-research-agent - To research specific libraries, frameworks, APIs, or technologies being integrated

4. Wait for ALL sub-tasks to complete before proceeding

5. Present findings and ask the user for design decisions

Step 3: Plan Structure Development

Once aligned on approach:

1. Create initial plan outline:

   For TDD Approach:

   Here's my proposed TDD plan structure following RED-GREEN-REFACTOR methodology:
   
   ## Overview
   [1-2 sentence summary]
   
   ## Implementation Approach
   Following Test-Driven Development (TDD) principles:
   1. **RED**: Create tests that define expected behavior (will fail initially)
   2. **GREEN**: Implement minimal code to make tests pass
   3. **REFACTOR**: Optimize and clean up implementation while keeping tests green
   
   ## Implementation Phases:
   1. **Phase 1: Create Tests (RED)** - Write comprehensive tests that define expected behavior
   2. **Phase 2: Core Implementation (GREEN)** - Implement minimal functionality to make tests pass
   3. **Phase 3: [Feature-specific Implementation]** - [Additional implementation phases as needed]
   4. **Phase N: Optimization & Refactoring** - Clean up and optimize while maintaining test coverage
   
   Does this TDD structure work for your implementation? Should I adjust the phases?
   

   For Traditional Approach:

   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 from the user before writing details

Step 4: Gather Metadata and Generate Permalinks

Before writing the plan:

1. Gather metadata for the plan document:

   • Generate current date: date '+%Y-%m-%d %H:%M:%S %Z'
   • Generate filename timestamp: date '+%Y-%m-%d'
   • Get git info (check first with git rev-parse --is-inside-work-tree 2>/dev/null):
     • If in a git repo:
       • Commit: git rev-parse HEAD
       • Branch: git branch --show-current 2>/dev/null || git rev-parse --abbrev-ref HEAD
       • Repository: basename $(git rev-parse --show-toplevel)
       • Researcher email: git config --get user.email
     • If NOT in a git repo: leave git fields empty in the frontmatter
   • Filename: thoughts/shared/plans/{timestamp}_{descriptive_name}.md

2. Generate permalinks if applicable (for Azure DevOps, GitHub, etc.):

   • Check if branch has been pushed to remote
   • Generate permanent links to code references if possible

Step 5: Detailed Plan Writing

After metadata and permalink generation:

1. Write the plan to thoughts/shared/plans/{timestamp}_{descriptive_name}.md (using timestamp from step 4)
2. Replace local file references with permalinks if available
3. Use this template structure:

---
date: [Current date and time with timezone in ISO format]
researcher: [Researcher email from git config]
git_commit: [Current commit hash]
branch: [Current branch name]
repository: [Repository name]
task: "[Task/Feature Name]"
tags: [implementation-plan, relevant-component-names]
status: draft
last_updated: [Current date in YYYY-MM-DD format]
last_updated_by: [Researcher email]
---

# [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 reference (file:line or permalink)]
- [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, including TDD methodology if applicable]

## Phase 1: [Descriptive Name]

### Phase 1: Overview
[What this phase accomplishes]

### Phase 1: Changes Required

#### 1. [Component/File Group]
**File**: `path/to/file` (permalink if available)
**Changes**: [Summary of changes]

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

Phase 1: Success Criteria

Phase 1: Automated Verification

Run verification commands from repository root:

• Type checking passes on changed files: Run your project's type checker
• Unit tests pass: Run your project's test suite for the relevant files
• Linting passes: Run your project's linter
• Application starts successfully: Verify the application runs without errors

Phase 1: Manual Verification

• Feature works as expected in the application
• Test functionality manually

Phase 1: Discoveries and Notable Information

[This section is filled by the implementing agent during Phase 1 execution.]

---

Phase 2: [Descriptive Name]

[Continue with same structure...]

---

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]
2. [Another verification step]

Performance Considerations

[Any performance implications or optimizations needed]

Migration Notes

[If applicable, how to handle existing data/systems]

References

• Original ticket: thoughts/neil/tickets/eng_XXXX.md
• Related research: thoughts/shared/research/[relevant].md
• Similar implementation: (file:line or permalink)

### Step 6: Review and Iteration

1. **Present the draft plan location**
2. **Iterate based on feedback**
3. **Continue refining** until the user is satisfied

## Important Guidelines

1. **Be Skeptical**: Question vague requirements, identify issues early, don't assume - verify with code

2. **Be Interactive**: Don't write the full plan in one shot, get buy-in at each step, ask the user for input

3. **Be Thorough**: Read all context files COMPLETELY, research actual code patterns, include specific file references

4. **Be Practical**: Focus on incremental, testable changes, consider migration and rollback, include "what we're NOT doing"

5. **Track Progress**: Track your planning tasks

6. **No Open Questions in Final Plan**: If you encounter open questions during planning, STOP and research or ask

7. **Ask the User**: ALWAYS use structured questions when gathering user input

## Success Criteria Guidelines

**Always separate success criteria into two categories:**

1. **Automated Verification** (can be run by execution agents):
   - Commands that can be run (type checking, tests, linting)
   - Specific files that should exist
   - Application startup verification

2. **Manual Verification** (requires human testing):
   - UI/UX functionality
   - Performance under real conditions
   - Edge cases that are hard to automate
   - User acceptance criteria

## Sub-task Spawning Best Practices

When spawning research sub-tasks:

1. **Spawn multiple tasks in parallel** for efficiency
2. **Each task should be focused** on a specific area
3. **Provide detailed instructions** including what to search for and expected output format
4. **Wait for all tasks to complete** before synthesizing
5. **Verify sub-task results** against the actual codebase

## Documentation Research Agent Usage

**When to Use the dex:documentation-research-agent**:

Use this agent proactively whenever the implementation plan involves:
- **New Library Integration**: Adding support for new libraries
- **Framework Features**: Implementing features using frameworks
- **API Integration**: Working with external APIs
- **Database Technologies**: New database drivers, ORMs, or query builders
- **Cloud Services**: Integrating with cloud providers
- **Development Tools**: Adding support for new build tools, testing frameworks, etc.