Create Plan

---
name: create-plan
description: Create detailed implementation plans through interactive, iterative
  collaboration. Use when the user needs to plan a feature, refactoring, or task.
argument-hint: "[work item reference or description]"
allowed-tools:
  - Bash(accelerator config *)
  - Bash(accelerator corpus metadata derive)
  - Bash(accelerator corpus frontmatter validate *)
---

# Implementation Plan

!`accelerator config context --skill create-plan --fail-safe`
!`accelerator config agents --fail-safe`

If no "Agent Names" section appears above, use these defaults:
accelerator:reviewer, accelerator:codebase-locator,
accelerator:codebase-analyser, accelerator:codebase-pattern-finder,
accelerator:documents-locator, accelerator:documents-analyser,
accelerator:web-search-researcher.

**Plans directory**: !`accelerator config path plans --fail-safe`
**Work items directory**: !`accelerator config path work --fail-safe`

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 command is invoked:

1. **Check if parameters were provided**:

- If a file path or work item 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/work item description (or reference to a work item 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 command with a work item file directly: `/create-plan @meta/work/eng-1234.md` (where the work items directory is shown above)
For deeper analysis, try: `/create-plan think deeply about @meta/work/eng-1234.md`
```

Then wait for the user's input.

## Process Steps

### Step 1: Context Gathering & Initial Analysis

1. **Read all mentioned files immediately and FULLY**:

- Work item files in the configured work items directory
- 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 **{codebase locator agent}** agent to find all files related to the
  work item or task
- Use the **{codebase analyser agent}** agent to understand how the current
  implementation works
- If relevant, use the **{documents locator agent}** agent to find any existing
  documents about this feature

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 work item 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 work item 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:

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** 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:**

- **{codebase locator agent}** - To find more specific files (e.g., "find all files that
  handle [specific component]")
- **{codebase analyser agent}** - To understand implementation details (e.g., "analyze
  how [system] works")
- **{codebase pattern finder agent}** - To find similar features we can model after

**For historical context:**

- **{documents locator agent}** - To find any research, plans, or decisions about this
  area
- **{documents analyser 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

3. **Wait for ALL sub-tasks to complete** before proceeding

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:

1. **Write the plan** to
   `!`accelerator config path plans --fail-safe``/YYYY-MM-DD-ENG-XXXX-description.md

- Format: `YYYY-MM-DD-ENG-XXXX-description.md` where:
  - YYYY-MM-DD is today's date
  - ENG-XXXX is the work item number (omit if no work item)
  - description is a brief kebab-case description
- Examples:
  - With work item: `2025-01-08-ENG-1478-parent-child-tracking.md`
  - Without work item: `2025-01-08-improve-error-handling.md`

2. **Use this template structure**:

!`accelerator config template plan --fail-safe`

### Step 5: Populate frontmatter

Before writing the plan file, capture metadata and substitute the
unified base fields into the template's frontmatter block:

1. Invoke `accelerator corpus metadata derive`
   to obtain `Current Date/Time (UTC):`, `Current Revision:`, and
   `Repository Name:`.
2. **Substitute** every field below with the indicated value:
   - `type:` ← `plan`
   - `id:` ← the filename stem (the file path computed above without
     `.md`), always quoted as a YAML string
   - `title:` ← the H1 title `{Feature/Task Name} Implementation Plan`
   - `date:` ← the `Current Date/Time (UTC):` value
   - `author:` ← the author resolved per the standard chain
     (config → VCS user → prompt)
   - `producer:` ← `create-plan`
   - `status:` ← `draft`
   - `work_item_id:` ← the linked work item as a typed-linkage ref `"work-item:NNNN"`.
     Fill in this form when invoked with a work item argument; otherwise
     omit the key entirely (do not carry an empty placeholder).
   - `revision:` ← the `Current Revision:` value
   - `repository:` ← the `Repository Name:` value
   - `last_updated:` ← the same `Current Date/Time (UTC):` value
   - `last_updated_by:` ← the same value resolved for `author`
   - `schema_version:` ← `1` (bare integer)

   Optional linkage/lifecycle keys are omit-by-default: the
   template shows each as `""`/`[]`, but write a key into the artifact
   **only** when it has a value, and omit it entirely otherwise (do not
   carry the empty placeholder through). By default a new plan draft
   names none of them.

   - `parent:` ← the owning work item as a typed-linkage ref
     (`"work-item:NNNN"`). Fill when the plan is owned by a work item;
     otherwise omit the key.
   - `blocks:` ← list of typed-linkage refs to plans this plan blocks
     (`["plan:NNNN", ...]`). Fill when blocking edges are explicit;
     otherwise omit the key.
   - `blocked_by:` ← list of typed-linkage refs to plans that block this
     one. Prefer writing the canonical `blocks:` on the other side; emit
     `blocked_by:` only when the canonical side cannot be written, and
     omit it otherwise.
   - `derived_from:` ← list of typed-linkage refs to research this plan
     was informed by (`["codebase-research:NNNN", ...]`). Fill when the
     plan derives from research; otherwise omit the key.
   - `relates_to:` ← list of typed-linkage refs to related artifacts.
     Fill when relationships are explicit; otherwise omit the key.
   - `reviewer:` ← name/email of the plan reviewer. Leave for review-plan
     to fill; omit the key on a fresh draft until the plan is reviewed.
3. Write the file with the substituted frontmatter block.

**Validate the frontmatter**: after writing, run `corpus frontmatter
validate` over the plan you just wrote:

```bash
accelerator corpus frontmatter validate --file <path>
```

If it exits non-zero, the plan document violates the canonical frontmatter
standard; report the emitted violation and fix the frontmatter before
completing.

### Step 6: Sync and Review

1. **Present the draft plan location**:
   ```
   I've created the initial implementation plan at:
   `{configured plans directory}/YYYY-MM-DD-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?
   ```

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` 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**:

- 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 {work_dir}/eng-1478.md
Assistant: Let me read that work item file completely first...

[Reads file fully]

Based on the work item, I understand we need to track parent-child relationships for events in the webhook daemon. Before I start planning, I have some questions...

[Interactive process continues...]
```

!`accelerator config instructions create-plan --fail-safe`