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