| name | writing-plans |
| description | Create detailed implementation plans with granular tasks. Use before implementing features or complex changes. |
Writing Implementation Plans
Create detailed plans for engineers with minimal codebase familiarity. Break work into granular, testable tasks following TDD principles.
When to Use
- Before implementing new features
- Before complex refactoring
- When work spans multiple files/components
- When coordinating multi-agent work
Plan Location
Save all plans to: docs/plans/YYYY-MM-DD-<feature-name>.md
Plan Structure
Header (Required)
# Plan: [Feature Name]
**Goal:** [One sentence describing what this achieves]
**Architecture:** [2-3 sentences on approach]
**Tech Stack:** [Relevant technologies]
**Files Affected:**
- `path/to/file1.ts` - [what changes]
- `path/to/file2.ts` - [what changes]
Task Format
Each task = single 2-5 minute action:
## Task 1: [Descriptive Name]
**Action:** Create | Modify | Test
**Files:**
- Create: `src/components/Button.tsx`
- Test: `src/components/Button.test.tsx`
**Steps:**
1. Write failing test for [behavior]
2. Verify test fails with expected error
3. Implement minimal code to pass
4. Verify test passes
5. Commit: `test(button): add click handler test`
**Verification:**
- [ ] Test fails initially
- [ ] Test passes after implementation
- [ ] No other tests broken
Task Granularity
Each step should be:
- Single action (one file, one change)
- Independently verifiable
- Following TDD (test first)
- Committable
Too big: "Implement authentication system"
Right size: "Write failing test for login validation"
Design Principles
- DRY - Don't Repeat Yourself
- YAGNI - You Aren't Gonna Need It (no speculative features)
- TDD - Test first, always
After Writing Plan
Offer execution options:
- Subagent-Driven: Execute in current session with fresh subagent per task
- Parallel Session: User opens new session with executing-plans skill
Example Plan
# Plan: Add User Avatar Component
**Goal:** Display user avatar with fallback initials
**Architecture:** React component with image loading state, fallback to initials derived from user name
**Tech Stack:** React, TypeScript, Tailwind CSS
**Files Affected:**
- `src/components/Avatar.tsx` - new component
- `src/components/Avatar.test.tsx` - tests
- `src/components/index.ts` - export
## Task 1: Create Avatar Test File
**Action:** Create
**Files:** `src/components/Avatar.test.tsx`
**Steps:**
1. Create test file with describe block
2. Write failing test: renders initials when no image
3. Verify test fails (component doesn't exist)
**Verification:**
- [ ] Test file created
- [ ] Test fails with "Cannot find module"
## Task 2: Create Basic Avatar Component
**Action:** Create
**Files:** `src/components/Avatar.tsx`
**Steps:**
1. Create component that renders initials
2. Accept `name` prop, extract initials
3. Verify test from Task 1 passes
**Verification:**
- [ ] Component renders
- [ ] Test passes
- [ ] Initials display correctly
