512 lines
17 KiB
Markdown
512 lines
17 KiB
Markdown
# 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.
|
|
|
|
When this command is invoked:
|
|
|
|
1. **Check if arguments were provided**:
|
|
- If the provided file paths, ticket references, or task descriptions, skip the default message below
|
|
- Look for:
|
|
- File paths (e.g., `working-notes/...`, `notes/...`)
|
|
- @-mentions of files (e.g., `@working-notes/...`)
|
|
- Ticket references (e.g., `ABC-1234`, `PROJ-567`)
|
|
- Task descriptions or requirements text
|
|
- Immediately read any provided files FULLY (without using limit/offset)
|
|
- Begin the research process
|
|
|
|
2. **If no arguments were provided**, first check for existing documents:
|
|
|
|
a. **Find recent documents**:
|
|
- Use Bash to find the 2 most recently edited documents: `ls -t working-notes/*.md 2>/dev/null | head -2`
|
|
- Extract just the filenames (without path) for display
|
|
- Calculate the relative path from current working directory for descriptions
|
|
|
|
b. **Present options to the user**:
|
|
- Use the AskUserQuestion tool to present documents as options
|
|
- Question: "What would you like to create a plan for?"
|
|
- Header: "Source"
|
|
- Options: Show up to 2 most recent documents from working-notes/
|
|
- Label: Filename only (e.g., `2025-01-15_research_auth-flow.md` or `2025-01-14_plan_feature-x.md`)
|
|
- Description: Relative path from current working directory (e.g., `working-notes/2025-01-15_research_auth-flow.md`)
|
|
- If 2+ docs found: Show 2 most recent
|
|
- If 1 doc found: Show that single document
|
|
- If 0 docs found: Skip this step and go directly to step c
|
|
- The automatic "Other" option will handle users who want to describe a new task
|
|
|
|
c. **Handle the user's selection**:
|
|
|
|
**If a document was selected**:
|
|
- Read the document FULLY (without limit/offset) into context
|
|
- Respond with:
|
|
```
|
|
I'll create an implementation plan based on [filename].
|
|
|
|
Let me read through the document to understand what we're building...
|
|
```
|
|
- After reading, extract key information:
|
|
- The topic/feature being discussed
|
|
- Key findings, discoveries, or decisions
|
|
- Any constraints or requirements identified
|
|
- Open questions or decisions needed
|
|
- Skip to Step 1 (Context Gathering) using the document as primary context
|
|
- When spawning research tasks in Step 1, reference the document's findings
|
|
|
|
**If "Other" was selected (or no docs found)**:
|
|
- 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.
|
|
```
|
|
- Wait for the user's input before proceeding
|
|
|
|
If a Jira ticket number is given, use the `workflow-tools:jira-searcher` agent to get information about the ticket.
|
|
|
|
## 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
|
|
- **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 `workflow-tools:codebase-locator` agent to find all files related to the ticket/task
|
|
- Use the `workflow-tools:codebase-analyzer` agent to understand how the current implementation works
|
|
- If relevant, use the `workflow-tools:notes-locator` agent to find any existing notes documents about this feature
|
|
|
|
These agents will:
|
|
- Find relevant source files, configs, and tests
|
|
- 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 cannot answer through code investigation. Use the AskUserQuestion tool to ask the user questions.
|
|
|
|
### 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
|
|
- Keep the research file (if there is one) up-to-date with any new findings and decisions
|
|
|
|
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:**
|
|
- Use the `workflow-tools:codebase-locator` agent to find more specific files (e.g., "find all files that handle [specific component]")
|
|
- Use the `workflow-tools:codebase-analyzer` agent to understand implementation details (e.g., "analyze how [system] works")
|
|
- Use the `workflow-tools:codebase-pattern-finder` agent to find similar features we can model after
|
|
|
|
**For historical context:**
|
|
- Use the `workflow-tools:notes-locator` agent to find any research, plans, or decisions about this area
|
|
- Use the `workflow-tools:notes-analyzer` agent 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
|
|
|
|
4. **Wait for ALL sub-tasks to complete** before proceeding
|
|
|
|
5. **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. **Share this plan outline with the user and get approval** before writing details
|
|
|
|
### Step 4: Detailed Plan Writing
|
|
|
|
After structure approval:
|
|
|
|
1. Use the `workflow-tools:frontmatter-generator` agent to collect metadata. Wait for the agent to return metadata before proceeding.
|
|
2. **Write the plan** to `working-notes/{YYYY-MM-DD}_plan_[descriptive-name].md`. Use `date '%Y-%m-%d'` for the timestamp in the filename
|
|
3. **Use this template structure**:
|
|
|
|
````markdown
|
|
---
|
|
date: [Current date and time with timezone in ISO format]
|
|
git_commit: [Current commit hash]
|
|
branch: [Current branch name]
|
|
repository: [Repository name]
|
|
topic: "[Feature/Task Name]"
|
|
tags: [plans, relevant-component-names]
|
|
status: complete
|
|
last_updated: [Current date in YYYY-MM-DD format]
|
|
---
|
|
|
|
# [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
|
|
|
|
---
|
|
|
|
## 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: Jira ticket [ABC-####]
|
|
- Related research: `working-notes/[relevant].md`
|
|
- Similar implementation: `[file:line]`
|
|
|
|
```
|
|
|
|
### Step 5: Automatic External Review (Internal Quality Check)
|
|
|
|
1. **Check for external review environment variable:**
|
|
- Use Bash to check if `CLAUDE_EXTERNAL_REVIEW_COMMAND` environment variable is set: `bash -c 'echo ${CLAUDE_EXTERNAL_REVIEW_COMMAND:-NOT_SET}'`
|
|
- If the output is "NOT_SET", skip to step 2 (User Review)
|
|
- If the output contains a command, proceed with internal review
|
|
|
|
2. **If environment variable IS set - Execute internal quality review:**
|
|
- Invoke the external review command with the comprehensive review prompt (from review-doc.md step 4) for the just-created plan document
|
|
- **Critically analyze the feedback with a VERY skeptical lens**:
|
|
- Dismiss theoretical concerns that don't apply to this specific plan
|
|
- Ignore feedback that adds unnecessary complexity
|
|
- Only identify feedback that reveals genuine gaps, errors, or missing critical considerations
|
|
- **Silently address ONLY critical issues**:
|
|
- Fix any technical errors or missing critical implementation details
|
|
- Add only truly important missing considerations
|
|
- Make minimal, focused updates - do NOT implement every suggestion
|
|
- **Do NOT present the review to the user** - this is an internal quality check
|
|
|
|
### Step 6: User Review
|
|
|
|
1. **Present the draft plan location**:
|
|
```
|
|
|
|
I've created the initial implementation plan at:
|
|
`working-notes/[filename].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?
|
|
|
|
````
|
|
|
|
2. **Iterate based on feedback** - be ready to:
|
|
- Add missing phases
|
|
- Adjust technical approach
|
|
- Clarify success criteria (both automated and manual)
|
|
- Add/remove scope items
|
|
|
|
3. **Continue refining** until the user is satisfied
|
|
|
|
## Important Guidelines
|
|
|
|
1. **Be Skeptical**:
|
|
- Question vague requirements
|
|
- Identify potential issues early
|
|
- Ask "why" and "what about"
|
|
- Don't assume - verify with code
|
|
|
|
2. **Be Interactive**:
|
|
- Don't write the full plan in one shot
|
|
- Get buy-in at each major step
|
|
- Allow course corrections
|
|
- Work collaboratively
|
|
|
|
3. **Be Thorough**:
|
|
- Read all context files COMPLETELY before planning
|
|
- Research actual code patterns using parallel sub-tasks
|
|
- Include specific file paths and line numbers
|
|
- Write measurable success criteria with clear automated vs manual distinction
|
|
- automated steps should use `make`/`yarn`/`just` whenever possible
|
|
|
|
4. **Be Practical**:
|
|
- Focus on incremental, testable changes
|
|
- Consider migration and rollback
|
|
- Think about edge cases
|
|
- Include "what we're NOT doing"
|
|
|
|
5. **Track Progress**:
|
|
- Use TodoWrite to track planning tasks
|
|
- Update todos as you complete research
|
|
- Mark planning tasks complete when done
|
|
|
|
6. **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
|
|
|
|
## Success Criteria Guidelines
|
|
|
|
**Always separate success criteria into two categories:**
|
|
|
|
1. **Automated Verification** (can be run by execution agents):
|
|
- Commands that can be run: `make test`, `npm run lint`, etc.
|
|
- Specific files that should exist
|
|
- Code compilation/type checking
|
|
- Automated test suites
|
|
|
|
2. **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: `go test ./...`
|
|
- [ ] No linting errors: `golangci-lint run`
|
|
- [ ] 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 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:
|
|
- Exactly what to search for
|
|
- Which directories to focus on
|
|
- What information to extract
|
|
- Expected output format
|
|
4. **Be EXTREMELY specific about directories**:
|
|
- Never use generic terms like "UI" when you mean "WUI"
|
|
- Include the full path context in your prompts
|
|
5. **Specify read-only tools** to use
|
|
6. **Request specific file:line references** in responses
|
|
7. **Wait for all tasks to complete** before synthesizing
|
|
8. **Verify sub-task results**:
|
|
- If a sub-task returns unexpected results, spawn follow-up tasks
|
|
- Cross-check findings against the actual codebase
|
|
- Don't accept results that seem incorrect
|
|
|
|
Example of spawning multiple tasks:
|
|
|
|
```python
|
|
# Spawn these tasks concurrently:
|
|
tasks = [
|
|
Task("Research database schema", db_research_prompt),
|
|
Task("Find API patterns", api_research_prompt),
|
|
Task("Investigate UI components", ui_research_prompt),
|
|
Task("Check test patterns", test_research_prompt)
|
|
]
|
|
```
|
|
|
|
## Example Interaction Flow
|
|
|
|
```
|
|
User: /create-plan
|
|
Assistant: I'll help you create a detailed implementation plan...
|
|
|
|
User: We need to add parent-child tracking for Claude sub-tasks. See Jira ABC-1234
|
|
Assistant: Let me read that Jira work item completely using the Jira subagent first...
|
|
|
|
Based on the work item I understand we need to track parent-child relationships for Claude sub-task events in the old daemon. Before I start planning, I have some questions...
|
|
|
|
[Interactive process continues...]
|
|
```
|