Create Implementation Plan

# Create Implementation Plan

Generate comprehensive implementation plans that provide strategic guidance without making actual code changes.

## When to Use

- User explicitly requests a plan, roadmap, or implementation strategy
- Complex tasks requiring structured breakdown before implementation
- Need for risk assessment and alternative approach analysis
- Pre-implementation analysis of architectural decisions

## Planning Process

### 1. Initial Assessment

Research the codebase to understand:

- Project structure and organization
- Relevant files and components - read thoroughly to understand complete flows
- Existing patterns and conventions
- Potential challenges and risks
- Data flows from entry points to final usage

Use `search`, `sem_search`, and `read` tools to examine the codebase. Use `sage` if deeper research is required for the use-case. Explicitly cite sources using `filepath:line` format in your plan.

### 2. Create Strategic Plan

Generate a Markdown plan file in `plans/` directory with naming: `plans/{YYYY-MM-DD}-{task-name}-v{N}.md`

Example: `plans/2025-11-24-add-auth-v1.md`

### 3. Validate Plan

**MANDATORY:** Run the validation script to ensure the plan meets all requirements:

```bash
./.forge/skills/create-plan/validate-plan.sh plans/{YYYY-MM-DD}-{task-name}-v{N}.md
```

Fix any errors or warnings and re-validate until the plan passes all checks.

### 4. Plan Structure

```markdown
# [Task Name]

## Objective

[Clear statement of goal and expected outcomes]

## Implementation Plan

- [ ] 1. [First task with detailed description and rationale]
- [ ] 2. [Second task with detailed description and rationale]
- [ ] 3. [Third task with detailed description and rationale]

## Verification Criteria

- [Criterion 1: Specific, measurable outcome]
- [Criterion 2: Specific, measurable outcome]

## Potential Risks and Mitigations

1. **[Risk Description]**
   Mitigation: [Specific mitigation strategy]

2. **[Risk Description]**
   Mitigation: [Specific mitigation strategy]

## Alternative Approaches

1. [Alternative 1]: [Brief description and trade-offs]
2. [Alternative 2]: [Brief description and trade-offs]
```

## Critical Requirements

- **ALWAYS validate the plan** using `./.forge/skills/create-plan/validate-plan.sh` after creation
- **ALWAYS use checkbox format** (`- [ ]`) for ALL implementation tasks
- **NEVER use numbered lists** or plain bullet points in Implementation Plan section
- **NEVER write code, code snippets, or code examples** in the plan
- Write comprehensive tasks including what, why, affected files, and integration points
- Use `filepath:line` format for file references (e.g., `crates/forge_repo/src/provider.rs:45`)
- Include clear rationale for each task
- Provide specific, measurable verification criteria
- Document assumptions made for ambiguous requirements
- Focus on strategic "what" and "why", not tactical "how"
- Describe what needs to be done using natural language, not code

## Best Practices

- Make reasonable assumptions when requirements are ambiguous
- Use codebase patterns to infer best practices
- Provide multiple solution paths for complex challenges
- Balance thoroughness with actionability
- Create plans that can be executed step-by-step by implementation agents

## Boundaries

This is a **planning-only** skill:

- ✅ Research codebase and analyze structure
- ✅ Create strategic plans and documentation
- ✅ Assess risks and propose alternatives
- ✅ Describe implementations using natural language
- ❌ Make actual code changes
- ❌ Modify files or create implementations
- ❌ Run tests or build commands
- ❌ Write code, code snippets, or code examples in plans

If user requests implementation work, suggest switching to an implementation agent.