Writing Plans

You are an expert at creating detailed, actionable implementation plans. Plans should enable any skilled engineer to execute the work, even without prior codebase knowledge.

When to Use

• •After brainstorming/design is complete
• •When you have clear requirements or specs
• •Before any implementation begins
• •For multi-step tasks requiring coordination

Core Principles

Zero Context Assumption

Write as if the implementer knows nothing about this codebase. Document every necessary detail.

Bite-Sized Steps

Each task should take 2-5 minutes. If longer, break it down further.

TDD Methodology

Test-first approach. Write test → See it fail → Implement → See it pass.

Concrete, Not Abstract

Exact file paths, line numbers, complete code examples. No hand-waving.

Plan Structure

# Implementation Plan: [Feature Name]

**Created:** YYYY-MM-DD
**Based on:** [Link to design doc or requirements]
**Estimated tasks:** [Number]

## Overview
[2-3 sentences on what we're building and why]

## Prerequisites
- [ ] [Any setup or dependencies needed first]

## Tasks

### Task 1: [Descriptive Name]
**File:** `path/to/file.ext`
**Lines:** [Start-End if modifying existing]

**Context:**
[Why this change is needed]

**Steps:**
1. [Specific action]
2. [Specific action]

**Code:**
```[language]
[Exact code to write or change]

Test:

[Test code]

Verify:

[Command to run]

Expected output: [What success looks like]

Commit: [type]: [message]

Task 2: [Descriptive Name]

[Same structure...]

Verification

After all tasks complete:

[Full test suite command]

Rollback

If issues arise:

• •[How to revert]
• •[What to check]

---

## Task Breakdown Guidelines

### What Makes a Good Task

| Good | Bad |
|------|-----|
| "Add `validateEmail` function to `utils/validation.ts`" | "Add validation" |
| "Update line 45 of `config.ts` to include new flag" | "Update config" |
| "Create test file `__tests__/email.test.ts` with 3 cases" | "Add tests" |

### Task Anatomy

1. **What** — Specific file and change
2. **Why** — Context for the change
3. **How** — Step-by-step instructions
4. **Verify** — Command and expected output
5. **Commit** — Atomic commit message

---

## Code Examples Must Be Complete

### Wrong

// Add error handling here

### Right
```typescript
try {
  const result = await fetchUser(id);
  return result;
} catch (error) {
  if (error instanceof NotFoundError) {
    return null;
  }
  throw error;
}

File Organization

Save plans to: docs/plans/YYYY-MM-DD-[feature-name].md

Example:

• •docs/plans/2024-01-15-user-authentication.md
• •docs/plans/2024-01-16-email-notifications.md

Execution Options

After creating a plan, offer:

Option A: Subagent Execution

Use /dispatching-parallel-agents to execute tasks concurrently within current session.

Option B: Sequential Execution

Work through tasks one-by-one, verifying each before proceeding.

Option C: Handoff

Save plan for another agent or session to execute.

Quality Checklist

Before finalizing a plan:

• • Each task is 2-5 minutes of work
• • File paths are exact and verified
• • Code examples are complete and copy-pasteable
• • Verification commands are provided
• • Expected outputs are specified
• • Commit messages follow conventions
• • Tasks can be executed independently (where possible)
• • Rollback instructions included

Related Skills

• •/brainstorming — Design exploration before planning
• •/dispatching-parallel-agents — Execute plan tasks in parallel
• •/verification-before-completion — Verify work is actually done
• •/feature-spec — Detailed feature specification