Plan Writing

Source: obra/superpowers

Overview

This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.

Task Breakdown Principles

1. Small, Focused Tasks

• Each task should take 2-5 minutes

• One clear outcome per task

• Independently verifiable

2. Clear Verification

• How do you know it's done?

• What can you check/test?

• What's the expected output?

3. Logical Ordering

• Dependencies identified

• Parallel work where possible

• Critical path highlighted

• Phase X: Verification is always LAST

4. Dynamic Naming in Project Root

• Plan files are saved as {task-slug}.md in the PROJECT ROOT

• Name derived from task (e.g., "add auth" → auth-feature.md)

• NEVER inside .claude/, docs/, or temp folders

Planning Principles (NOT Templates!)

🔴 NO fixed templates. Each plan is UNIQUE to the task.

Principle 1: Keep It SHORT

❌ Wrong

✅ Right

50 tasks with sub-sub-tasks

5-10 clear tasks max

Every micro-step listed

Only actionable items

Verbose descriptions

One-line per task

Rule: If plan is longer than 1 page, it's too long. Simplify.

Principle 2: Be SPECIFIC, Not Generic

❌ Wrong

✅ Right

"Set up project"

"Run npx create-next-app"

"Add authentication"

"Install next-auth, create /api/auth/[...nextauth].ts"

"Style the UI"

"Add Tailwind classes to Header.tsx"

Rule: Each task should have a clear, verifiable outcome.

Principle 3: Dynamic Content Based on Project Type

For NEW PROJECT:

• What tech stack? (decide first)

• What's the MVP? (minimal features)

• What's the file structure?

For FEATURE ADDITION:

• Which files are affected?

• What dependencies needed?

• How to verify it works?

For BUG FIX:

• What's the root cause?

• What file/line to change?

• How to test the fix?

Principle 4: Scripts Are Project-Specific

🔴 DO NOT copy-paste script commands. Choose based on project type.

Project Type

Relevant Scripts

Frontend/React

ux_audit.py, accessibility_checker.py

Backend/API

api_validator.py, security_scan.py

Mobile

mobile_audit.py

Database

schema_validator.py

Full-stack

Mix of above based on what you touched

Wrong: Adding all scripts to every plan

Right: Only scripts relevant to THIS task

Principle 5: Verification is Simple

❌ Wrong

✅ Right

"Verify the component works correctly"

"Run npm run dev, click button, see toast"

"Test the API"

"curl localhost:3000/api/users returns 200"

"Check styles"

"Open browser, verify dark mode toggle works"

Plan Structure (Flexible, Not Fixed!)

# [Task Name]

## Goal

One sentence: What are we building/fixing?

## Tasks

- [ ] Task 1: [Specific action] → Verify: [How to check]

- [ ] Task 2: [Specific action] → Verify: [How to check]

- [ ] Task 3: [Specific action] → Verify: [How to check]

## Done When

- [ ] [Main success criteria]

That's it. No phases, no sub-sections unless truly needed.

Keep it minimal. Add complexity only when required.

Notes

[Any important considerations]

---

## Best Practices (Quick Reference)

1. **Start with goal** - What are we building/fixing?

2. **Max 10 tasks** - If more, break into multiple plans

3. **Each task verifiable** - Clear "done" criteria

4. **Project-specific** - No copy-paste templates

5. **Update as you go** - Mark `[x]` when complete

---

## When to Use

- New project from scratch

- Adding a feature

- Fixing a bug (if complex)

- Refactoring multiple files

## Limitations

- Use this skill only when the task clearly matches the scope described above.

- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.