Plan Writing

1---
2name: plan-writing
3description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
4allowed-tools: Read, Glob, Grep
5---
6 
7# Plan Writing
8 
9> Source: obra/superpowers
10 
11## Overview
12This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
13 
14## Task Breakdown Principles
15 
16### 1. Small, Focused Tasks
17- Each task should take 2-5 minutes
18- One clear outcome per task
19- Independently verifiable
20 
21### 2. Clear Verification
22- How do you know it's done?
23- What can you check/test?
24- What's the expected output?
25 
26### 3. Logical Ordering
27- Dependencies identified
28- Parallel work where possible
29- Critical path highlighted
30- **Phase X: Verification is always LAST**
31 
32### 4. Dynamic Naming in Project Root
33- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
34- Name derived from task (e.g., "add auth" → `auth-feature.md`)
35- **NEVER** inside `.claude/`, `docs/`, or temp folders
36 
37## Planning Principles (NOT Templates!)
38 
39> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
40 
41### Principle 1: Keep It SHORT
42 
43| ❌ Wrong | ✅ Right |
44|----------|----------|
45| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
46| Every micro-step listed | Only actionable items |
47| Verbose descriptions | One-line per task |
48 
49> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
50 
51---
52 
53### Principle 2: Be SPECIFIC, Not Generic
54 
55| ❌ Wrong | ✅ Right |
56|----------|----------|
57| "Set up project" | "Run `npx create-next-app`" |
58| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
59| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
60 
61> **Rule:** Each task should have a clear, verifiable outcome.
62 
63---
64 
65### Principle 3: Dynamic Content Based on Project Type
66 
67**For NEW PROJECT:**
68- What tech stack? (decide first)
69- What's the MVP? (minimal features)
70- What's the file structure?
71 
72**For FEATURE ADDITION:**
73- Which files are affected?
74- What dependencies needed?
75- How to verify it works?
76 
77**For BUG FIX:**
78- What's the root cause?
79- What file/line to change?
80- How to test the fix?
81 
82---
83 
84### Principle 4: Scripts Are Project-Specific
85 
86> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
87 
88| Project Type | Relevant Scripts |
89|--------------|------------------|
90| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
91| Backend/API | `api_validator.py`, `security_scan.py` |
92| Mobile | `mobile_audit.py` |
93| Database | `schema_validator.py` |
94| Full-stack | Mix of above based on what you touched |
95 
96**Wrong:** Adding all scripts to every plan
97**Right:** Only scripts relevant to THIS task
98 
99---
100 
101### Principle 5: Verification is Simple
102 
103| ❌ Wrong | ✅ Right |
104|----------|----------|
105| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
106| "Test the API" | "curl localhost:3000/api/users returns 200" |
107| "Check styles" | "Open browser, verify dark mode toggle works" |
108 
109---
110 
111## Plan Structure (Flexible, Not Fixed!)
112 
113```
114# [Task Name]
115 
116## Goal
117One sentence: What are we building/fixing?
118 
119## Tasks
120- [ ] Task 1: [Specific action] → Verify: [How to check]
121- [ ] Task 2: [Specific action] → Verify: [How to check]
122- [ ] Task 3: [Specific action] → Verify: [How to check]
123 
124## Done When
125- [ ] [Main success criteria]
126```
127 
128> **That's it.** No phases, no sub-sections unless truly needed.
129> Keep it minimal. Add complexity only when required.
130 
131## Notes
132[Any important considerations]
133```
134 
135---
136 
137## Best Practices (Quick Reference)
138 
1391. **Start with goal** - What are we building/fixing?
1402. **Max 10 tasks** - If more, break into multiple plans
1413. **Each task verifiable** - Clear "done" criteria
1424. **Project-specific** - No copy-paste templates
1435. **Update as you go** - Mark `[x]` when complete
144 
145---
146 
147## When to Use
148 
149- New project from scratch
150- Adding a feature
151- Fixing a bug (if complex)
152- Refactoring multiple files
153