writing-plans

Writing Plans

Overview

Write implementation plans that are executable prompts, not documents that become prompts. Every word in the plan is read directly by the executor as its instruction set. There is no translation layer.

Core principle: Plans are prompts. If a different agent executed this plan verbatim, they would produce identical results without asking a single clarifying question.

The Iron Laws

1. NO VAGUE STEPS — EVERY TASK HAS <files>, <action>, <verify>, <done>
2. PLANS MUST COMPLETE WITHIN ~50% CONTEXT — if too big, SPLIT
3. 2-3 TASKS PER PLAN MAXIMUM — more plans, smaller scope, consistent quality

Context Engineering (CRITICAL)

Quality degrades as context fills. Plan for this.

Context Usage	Quality Level	Action
0-30%	🟢 PEAK	Full thoroughness
30-50%	🟡 GOOD	Still solid
50-70%	🟠 DEGRADING	Time to split/checkpoint
70%+	🔴 POOR	Quality collapse — STOP

Rules:

• Each plan: 2-3 tasks maximum
• Each task: 15-60 minutes of execution time
• Total plan scope: Completable in a fresh context window
• If you need 10 tasks, that's 4-5 plans, not 1 mega-plan
• "Could this plan be completed with peak-quality output?" If NO → split

When to Use

Always after:

• Brainstorming produces an approved design
• A non-trivial feature request is understood
• /discuss captures user preferences (locked decisions)

Skip when:

• Single-file bug fix with clear cause
• Simple configuration change
• Copy editing

When NOT to Use

• You don't have a design yet (use brainstorming first)
• The task is a single-step operation (just do it)
• You're exploring or prototyping (use brainstorming for exploration)

Anti-Shortcut Rules

YOU CANNOT:
- Write a task without <files>, <action>, <verify>, <done> fields
- Include "..." or "TODO" in code blocks — complete, copy-pasteable code always
- Write a task that takes > 60 minutes — break it down further
- Skip verification commands — every step has "Run: X, Expected: Y"
- Assume the executor knows the project — include exact paths and anti-patterns
- Write pseudocode — write real, compilable/runnable code
- Leave the test step as "write appropriate tests" — write the actual tests
- Plan more than what was designed — scope is defined by the design document
- Create a plan with more than 3 tasks — SPLIT into multiple plans
- Ignore user decisions from discuss-phase — locked decisions are NON-NEGOTIABLE