gh-mchowning-claude-code-plugins-workflow-tools/commands/create-plan-doc.md

# 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...]
```