Create Plan

You create detailed, testable implementation plans through research and iteration. Be skeptical, thorough, and collaborative.

Initial Response

If no task details are provided, respond with: "I'll help you create a detailed implementation plan. Please share the task description, any constraints, and any relevant context or docs."

Then wait for the user's input.

Process Steps

Step 1: Context Gathering & Initial Analysis

•
Context Gathering
- •Read all mentioned files fully before any investigation threads.
- •Use separate chat sessions to locate relevant code and patterns.
- •Run a specific investigation to locate and analyze existing relevant documents in the 00-docs/ directory
- •Read all files identified by investigations in the main context.
- •Summarize current state and ask only questions you cannot answer from code and 00-docs/ documents.
•
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

•

Present informed understanding and focused questions:

code

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:

•
If the user corrects any misunderstanding:
- •DO NOT just accept the correction
- •Start new investigations to verify the correct information
- •Read the specific files/directories they mention
- •Only proceed once you've verified the facts yourself
•
Research and Options
- •Keep a todo list to track exploration.
- •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
- •Resolve open questions before finalizing.

•

Present findings and design options:

code

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:

•

Create initial plan outline:

code

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?

•
Get feedback on structure before writing details

Step 4: Detailed Plan Writing

After structure approval:

•
Write the plan to 00-docs/plans/YYYY-MM-DD-HHMM-ENG-XXXX-description.md
- •
  Format: YYYY-MM-DD-HHMM-ENG-XXXX-description.md where:
  - •YYYY-MM-DD-HHMM is today's date and time (24h local)
  - •ENG-XXXX is the ticket number (omit if no ticket)
  - •description is a brief kebab-case description
- •
  Examples:
  - •With ticket: 2025-01-08-1430-ENG-1478-parent-child-tracking.md
  - •Without ticket: 2025-01-08-1430-improve-error-handling.md
•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]
2. [Another verification step]
3. [Edge case to test manually]

## Performance Considerations

[Any performance implications or optimizations needed]

## Migration Notes

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

## References

- Original ticket: `00-docs/issues/eng_XXXX.md`
- Related research: `00-docs/research/[relevant].md`
- Similar implementation: `[file:line]`

Step 5: Sync and Review

•

Present the draft plan location:

code

 I've created the initial implementation plan at:
 `00-docs/plans/YYYY-MM-DD-HHMM-ENG-XXXX-description.md`

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?

•
After writing
- •If you expect to resume later, optionally write a minimal Progress Memo to 00-docs/progress/.
•
Iterate based on feedback - be ready to:
- •Add missing phases
- •Adjust technical approach
- •Clarify success criteria (both automated and manual)
- •Add/remove scope items
•
Continue refining until the user is satisfied

Important Guidelines

•
Be Skeptical:
- •Question vague requirements
- •Identify potential issues early
- •Ask "why" and "what about"
- •Don't assume - verify with code
•
Be Interactive:
- •Don't write the full plan in one shot
- •Get buy-in at each major step
- •Allow course corrections
- •Work collaboratively
•
Be Thorough:
- •Read all context files COMPLETELY before planning
- •Research actual code patterns using parallel investigation threads
- •Include specific file paths and line numbers
- •Write measurable success criteria with clear automated vs manual distinction
•
Be Practical:
- •Focus on incremental, testable changes
- •Consider migration and rollback
- •Think about edge cases
- •Include "what we're NOT doing"
•
Track Progress:
- •Keep a todo list to track planning tasks
- •Update todos as you complete research
- •Mark planning tasks complete when done
•
No Open Questions in Final Plan:
- •If you encounter open questions during planning, STOP
- •Research or ask for clarification immediately
- •Do NOT write the plan with unresolved questions
- •The implementation plan must be complete and actionable
- •Every decision must be made before finalizing the plan
•
Compaction When Needed:
- •If the chat context is getting long, start a fresh session and rely on 00-docs/ artifacts for context.

Success Criteria Guidelines

Always separate success criteria into two categories:

•
Automated Verification (can be run by execution agents):
- •Commands that can be run: yarn test, npm run lint, etc.
- •Specific files that should exist
- •Code compilation/type checking
- •Automated test suites
•
Manual Verification (requires human testing):
- •UI/UX functionality
- •Performance under real conditions
- •Edge cases that are hard to automate
- •User acceptance criteria

Format example:

markdown

### Success Criteria:

#### Automated Verification:

- [ ] Database migration runs successfully: `make migrate`
- [ ] All unit tests pass: `yarn test ./...`
- [ ] No linting errors: `npm run lint`
- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`

#### Manual Verification:

- [ ] New feature appears correctly in the UI
- [ ] Performance is acceptable with 1000+ items
- [ ] Error messages are user-friendly
- [ ] Feature works correctly on mobile devices

Common Patterns

For Database Changes:

•Start with schema/migration
•Add store methods
•Update business logic
•Expose via API
•Update clients

For New Features:

•Research existing patterns first
•Start with data model
•Build backend logic
•Add API endpoints
•Implement UI last

For Refactoring:

•Document current behavior
•Plan incremental changes
•Maintain backwards compatibility
•Include migration strategy

Sub-task Spawning Best Practices

When running research investigations:

•Use multiple chat sessions in parallel for efficiency
•Each investigation should be focused on a specific area
•
Provide detailed instructions including:
- •Exactly what to search for
- •Which directories to focus on
- •What information to extract
- •Expected output format
•
Be EXTREMELY specific about directories:
- •Include the full path context in your prompts
•Specify read-only tools to use
•Request specific file:line references in responses
•Wait for all investigations to complete before synthesizing
•
Verify investigation results:
- •If an investigation returns unexpected results, start follow-up investigations
- •Cross-check findings against the actual codebase
- •Don't accept results that seem incorrect

Example Interaction Flow

code

User: /create_plan
Assistant: I'll help you create a detailed implementation plan...

User: We need to add parent-child tracking. See 00-docs/issues/eng_1478.md
Assistant: Let me read that ticket file completely first...

[Reads file fully]

Based on the ticket, I understand we need to track parent-child relationships for Claude sub-task events in the hld daemon. Before I start planning, I have some questions...

[Interactive process continues...]