feat(04-02): 70% context reduction for plan-phase (scope-estimation 74%, plan-phase.md 66%)
- scope-estimation.md: 451 → 115 lines (removed ASCII art, collapsed anti-patterns) - plan-phase.md workflow: 864 → 290 lines (condensed discovery tree, removed verbose examples) - Total Phase 4 context reduction: 101KB → 30KB (exceeds 37% target)
This commit is contained in:
@@ -1,447 +1,111 @@
|
||||
<scope_estimation>
|
||||
Plans must maintain consistent quality from first task to last. This requires understanding the **quality degradation curve** and splitting aggressively to stay in the peak quality zone.
|
||||
Plans must maintain consistent quality from first task to last. This requires understanding quality degradation and splitting aggressively.
|
||||
|
||||
<quality_degradation_curve>
|
||||
<quality_insight>
|
||||
Claude degrades when it *perceives* context pressure and enters "completion mode."
|
||||
|
||||
**Critical insight:** Claude doesn't degrade at arbitrary percentages - it degrades when it *perceives* context pressure and enters "completion mode."
|
||||
| Context Usage | Quality | Claude's State |
|
||||
|---------------|---------|----------------|
|
||||
| 0-30% | PEAK | Thorough, comprehensive |
|
||||
| 30-50% | GOOD | Confident, solid work |
|
||||
| 50-70% | DEGRADING | Efficiency mode begins |
|
||||
| 70%+ | POOR | Rushed, minimal |
|
||||
|
||||
```
|
||||
Context Usage │ Quality Level │ Claude's Mental State
|
||||
─────────────────────────────────────────────────────────
|
||||
0-30% │ ████████ PEAK │ "I can be thorough and comprehensive"
|
||||
│ │ No anxiety, full detail, best work
|
||||
**The 40-50% inflection point:** Claude sees context mounting and thinks "I'd better conserve now." Result: "I'll complete the remaining tasks more concisely" = quality crash.
|
||||
|
||||
30-50% │ ██████ GOOD │ "Still have room, maintaining quality"
|
||||
│ │ Engaged, confident, solid work
|
||||
|
||||
50-70% │ ███ DEGRADING │ "Getting tight, need to be efficient"
|
||||
│ │ Efficiency mode, compression begins
|
||||
|
||||
70%+ │ █ POOR │ "Running out, must finish quickly"
|
||||
│ │ Self-lobotomization, rushed, minimal
|
||||
```
|
||||
|
||||
**The 40-50% inflection point:**
|
||||
|
||||
This is where quality breaks. Claude sees context mounting and thinks "I'd better conserve now or I won't finish." Result: The classic mid-execution statement "I'll complete the remaining tasks more concisely" = quality crash.
|
||||
|
||||
**The fundamental rule:** Stop BEFORE quality degrades, not at context limit.
|
||||
</quality_degradation_curve>
|
||||
**The rule:** Stop BEFORE quality degrades, not at context limit.
|
||||
</quality_insight>
|
||||
|
||||
<context_target>
|
||||
|
||||
**Plans should complete within ~50% of context usage.**
|
||||
|
||||
Why 50% not 80%?
|
||||
- Huge safety buffer
|
||||
- No context anxiety possible
|
||||
- Quality maintained from start to finish
|
||||
- Quality maintained start to finish
|
||||
- Room for unexpected complexity
|
||||
- Space for iteration and fixes
|
||||
|
||||
**If you target 80%, you're planning for failure.** By the time you hit 80%, you've already spent 40% in degradation mode.
|
||||
- If you target 80%, you've already spent 40% in degradation mode
|
||||
</context_target>
|
||||
|
||||
<task_rule>
|
||||
**Each plan: 2-3 tasks maximum. Stay under 50% context.**
|
||||
|
||||
**Each plan should contain 2-3 tasks maximum. Context usage matters more than task count.**
|
||||
|
||||
**The real measure: Stay under 50% context usage.**
|
||||
|
||||
Task count is a proxy for context. Adjust based on task complexity:
|
||||
|
||||
**Simple tasks (CRUD, config, basic features):**
|
||||
- 3 tasks is fine
|
||||
- Each burns ~10-15% context
|
||||
- Total: ~30-45% → Safe
|
||||
|
||||
**Complex tasks (auth, payments, architecture, integrations):**
|
||||
- Stick to 2 tasks
|
||||
- Each burns ~20-30% context
|
||||
- Total: ~40-50% → At limit
|
||||
|
||||
**Very complex tasks (migrations, major refactors, novel patterns):**
|
||||
- Consider 1-2 tasks only
|
||||
- Each can burn 30-40% context
|
||||
- Splitting to 1 task/plan is valid for high complexity
|
||||
|
||||
**Context estimation by task type:**
|
||||
|
||||
**Task 1 (0-15% context for simple, 0-30% for complex):**
|
||||
- Fresh context
|
||||
- Peak quality
|
||||
- Comprehensive implementation
|
||||
- Full testing
|
||||
|
||||
**Task 2 (15-35% context for simple, 30-50% for complex):**
|
||||
- Still good quality
|
||||
- Context pressure manageable
|
||||
- Natural stopping point for complex work
|
||||
|
||||
**Task 3 (35-50% context for simple only):**
|
||||
- Only include for simple tasks
|
||||
- Skip for complex work
|
||||
- Better to split complex work at 2 tasks
|
||||
|
||||
**Task 4+ (50%+ context):**
|
||||
- NEVER do this
|
||||
- Quality guaranteed to degrade
|
||||
- Should have split earlier
|
||||
| Task Complexity | Tasks/Plan | Context/Task | Total |
|
||||
|-----------------|------------|--------------|-------|
|
||||
| Simple (CRUD, config) | 3 | ~10-15% | ~30-45% |
|
||||
| Complex (auth, payments) | 2 | ~20-30% | ~40-50% |
|
||||
| Very complex (migrations, refactors) | 1-2 | ~30-40% | ~30-50% |
|
||||
|
||||
**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
|
||||
|
||||
**The principle:** Each plan completes within 50% context. Task count is flexible based on complexity.
|
||||
</task_rule>
|
||||
|
||||
<split_signals>
|
||||
|
||||
<always_split>
|
||||
|
||||
**1. More than 3 tasks**
|
||||
- Even if tasks seem small
|
||||
- Each additional task increases degradation risk
|
||||
- Split into logical groups of 2-3
|
||||
|
||||
**2. Multiple subsystems**
|
||||
```
|
||||
❌ Bad (1 plan):
|
||||
- Database schema (3 files)
|
||||
- API routes (5 files)
|
||||
- UI components (8 files)
|
||||
Total: 16 files, 1 plan → guaranteed degradation
|
||||
|
||||
✅ Good (3 plans):
|
||||
- 01-01-PLAN.md: Database schema (3 files, 2 tasks)
|
||||
- 01-02-PLAN.md: API routes (5 files, 3 tasks)
|
||||
- 01-03-PLAN.md: UI components (8 files, 3 tasks)
|
||||
Total: 16 files, 3 plans → consistent quality
|
||||
```
|
||||
|
||||
**3. Any task with >5 file modifications**
|
||||
- Large tasks burn context fast
|
||||
- Split by file groups or logical units
|
||||
- Better: 3 plans of 2 files each vs 1 plan of 6 files
|
||||
|
||||
**4. Checkpoint + implementation work**
|
||||
- Checkpoints require user interaction (context preserved)
|
||||
- Implementation after checkpoint should be separate plan
|
||||
|
||||
✅ Good split:
|
||||
- 02-01-PLAN.md: Setup (checkpoint: decision on auth provider)
|
||||
- 02-02-PLAN.md: Implement chosen auth solution
|
||||
|
||||
**5. Discovery + implementation**
|
||||
- Discovery produces DISCOVERY.md (separate plan)
|
||||
- Implementation consumes DISCOVERY.md (separate plan)
|
||||
- Clear boundary, clean handoff
|
||||
- **More than 3 tasks** - Even if tasks seem small
|
||||
- **Multiple subsystems** - DB + API + UI = separate plans
|
||||
- **Any task with >5 file modifications** - Split by file groups
|
||||
- **Checkpoint + implementation work** - Checkpoints in one plan, implementation after in separate plan
|
||||
- **Discovery + implementation** - DISCOVERY.md in one plan, implementation in another
|
||||
</always_split>
|
||||
|
||||
<consider_splitting>
|
||||
|
||||
**1. Estimated >5 files modified total**
|
||||
- Context from reading existing code
|
||||
- Context from diffs
|
||||
- Context from responses
|
||||
- Adds up faster than expected
|
||||
|
||||
**2. Complex domains (auth, payments, data modeling)**
|
||||
- These require careful thinking
|
||||
- Burns more context per task than simple CRUD
|
||||
- Split more aggressively
|
||||
|
||||
**3. Any uncertainty about approach**
|
||||
- "Figure out X" phase separate from "implement X" phase
|
||||
- Don't mix exploration and implementation
|
||||
|
||||
**4. Natural semantic boundaries**
|
||||
- Setup → Core → Features
|
||||
- Backend → Frontend
|
||||
- Configuration → Implementation → Testing
|
||||
- Estimated >5 files modified total
|
||||
- Complex domains (auth, payments, data modeling)
|
||||
- Any uncertainty about approach
|
||||
- Natural semantic boundaries (Setup -> Core -> Features)
|
||||
</consider_splitting>
|
||||
</split_signals>
|
||||
|
||||
<splitting_strategies>
|
||||
**By subsystem:** Auth → 01: DB models, 02: API routes, 03: Protected routes, 04: UI components
|
||||
|
||||
<by_subsystem>
|
||||
**By dependency:** Payments → 01: Stripe setup, 02: Subscription logic, 03: Frontend integration
|
||||
|
||||
**Phase:** "Authentication System"
|
||||
**By complexity:** Dashboard → 01: Layout shell, 02: Data fetching, 03: Visualization
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 03-01-PLAN.md: Database models (User, Session tables + relations)
|
||||
- 03-02-PLAN.md: Auth API (register, login, logout endpoints)
|
||||
- 03-03-PLAN.md: Protected routes (middleware, JWT validation)
|
||||
- 03-04-PLAN.md: UI components (login form, registration form)
|
||||
```
|
||||
|
||||
Each plan: 2-3 tasks, single subsystem, clean commits.
|
||||
</by_subsystem>
|
||||
|
||||
<by_dependency>
|
||||
|
||||
**Phase:** "Payment Integration"
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 04-01-PLAN.md: Stripe setup (webhook endpoints via API, env vars, test mode)
|
||||
- 04-02-PLAN.md: Subscription logic (plans, checkout, customer portal)
|
||||
- 04-03-PLAN.md: Frontend integration (pricing page, payment flow)
|
||||
```
|
||||
|
||||
Later plans depend on earlier completion. Sequential execution, fresh context each time.
|
||||
</by_dependency>
|
||||
|
||||
<by_complexity>
|
||||
|
||||
**Phase:** "Dashboard Buildout"
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 05-01-PLAN.md: Layout shell (simple: sidebar, header, routing)
|
||||
- 05-02-PLAN.md: Data fetching (moderate: TanStack Query setup, API integration)
|
||||
- 05-03-PLAN.md: Data visualization (complex: charts, tables, real-time updates)
|
||||
```
|
||||
|
||||
Complex work gets its own plan with full context budget.
|
||||
</by_complexity>
|
||||
|
||||
<by_verification_points>
|
||||
|
||||
**Phase:** "Deployment Pipeline"
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 06-01-PLAN.md: Vercel setup (deploy via CLI, configure domains)
|
||||
→ Ends with checkpoint:human-verify "check xyz.vercel.app loads"
|
||||
|
||||
- 06-02-PLAN.md: Environment config (secrets via CLI, env vars)
|
||||
→ Autonomous (no checkpoints) → subagent execution
|
||||
|
||||
- 06-03-PLAN.md: CI/CD (GitHub Actions, preview deploys)
|
||||
→ Ends with checkpoint:human-verify "check PR preview works"
|
||||
```
|
||||
|
||||
Verification checkpoints create natural boundaries. Autonomous plans between checkpoints execute via subagent with fresh context.
|
||||
</by_verification_points>
|
||||
**By verification:** Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint)
|
||||
</splitting_strategies>
|
||||
|
||||
<autonomous_vs_interactive>
|
||||
|
||||
**Critical optimization:** Plans without checkpoints don't need main context.
|
||||
|
||||
<autonomous_plans>
|
||||
- Contains only `type="auto"` tasks
|
||||
- No user interaction needed
|
||||
- **Execute via subagent with fresh 200k context**
|
||||
- Impossible to degrade (always starts at 0%)
|
||||
- Creates SUMMARY, commits, reports back
|
||||
- Can run in parallel (multiple subagents)
|
||||
</autonomous_plans>
|
||||
|
||||
<interactive_plans>
|
||||
- Contains `checkpoint:human-verify` or `checkpoint:decision` tasks
|
||||
- Requires user interaction
|
||||
- Must execute in main context
|
||||
- Still target 50% context (2-3 tasks)
|
||||
|
||||
**Planning guidance:** If splitting a phase, try to:
|
||||
- Group autonomous work together (→ subagent)
|
||||
- Separate interactive work (→ main context)
|
||||
- Maximize autonomous plans (more fresh contexts)
|
||||
|
||||
Example:
|
||||
```
|
||||
Phase: Feature X
|
||||
- 07-01-PLAN.md: Backend (autonomous) → subagent
|
||||
- 07-02-PLAN.md: Frontend (autonomous) → subagent
|
||||
- 07-03-PLAN.md: Integration test (has checkpoint:human-verify) → main context
|
||||
```
|
||||
|
||||
Two fresh contexts, one interactive verification. Perfect.
|
||||
</interactive_plans>
|
||||
</autonomous_vs_interactive>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
<antipattern_comprehensive>
|
||||
|
||||
**Bad - Comprehensive plan:**
|
||||
```
|
||||
Plan: "Complete Authentication System"
|
||||
Tasks:
|
||||
1. Database models
|
||||
2. Migration files
|
||||
3. Auth API endpoints
|
||||
4. JWT utilities
|
||||
5. Protected route middleware
|
||||
6. Password hashing
|
||||
7. Login form component
|
||||
8. Registration form component
|
||||
|
||||
Result: 8 tasks, 80%+ context, degradation at task 4-5
|
||||
Tasks: 8 (models, migrations, API, JWT, middleware, hashing, login form, register form)
|
||||
Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- Task 1-3: Good quality
|
||||
- Task 4-5: "I'll do these concisely" = degradation begins
|
||||
- Task 6-8: Rushed, minimal, poor quality
|
||||
</antipattern_comprehensive>
|
||||
|
||||
<pattern_atomic>
|
||||
|
||||
**Good - Atomic plans:**
|
||||
```
|
||||
Split into 4 plans:
|
||||
|
||||
Plan 1: "Auth Database Models" (2 tasks)
|
||||
- Database schema (User, Session)
|
||||
- Migration files
|
||||
|
||||
Plan 2: "Auth API Core" (3 tasks)
|
||||
- Register endpoint
|
||||
- Login endpoint
|
||||
- JWT utilities
|
||||
|
||||
Plan 3: "Auth API Protection" (2 tasks)
|
||||
- Protected route middleware
|
||||
- Logout endpoint
|
||||
|
||||
Plan 4: "Auth UI Components" (2 tasks)
|
||||
- Login form
|
||||
- Registration form
|
||||
Each: 30-40% context, peak quality, focused commits
|
||||
```
|
||||
|
||||
**Why this succeeds:**
|
||||
- Each plan: 2-3 tasks, 30-40% context
|
||||
- All tasks: Peak quality throughout
|
||||
- Git history: 4 focused commits
|
||||
- Easy to verify each piece
|
||||
- Rollback is surgical
|
||||
</pattern_atomic>
|
||||
|
||||
<antipattern_efficiency_trap>
|
||||
|
||||
```
|
||||
Thinking: "These tasks are small, let's do 6 to be efficient"
|
||||
|
||||
Result: Task 1-2 are good, task 3-4 begin degrading, task 5-6 are rushed
|
||||
```
|
||||
|
||||
**Why this fails:** You're optimizing for fewer plans, not quality. The "efficiency" is false - poor quality requires more rework.
|
||||
</antipattern_efficiency_trap>
|
||||
|
||||
<pattern_quality_first>
|
||||
|
||||
```
|
||||
Thinking: "These tasks are small, but let's do 2-3 to guarantee quality"
|
||||
|
||||
Result: All tasks peak quality, clean commits, no rework needed
|
||||
```
|
||||
|
||||
**Why this succeeds:** You optimize for quality, which is true efficiency. No rework = faster overall.
|
||||
</pattern_quality_first>
|
||||
</anti_patterns>
|
||||
|
||||
<estimating_context>
|
||||
| Files Modified | Context Impact |
|
||||
|----------------|----------------|
|
||||
| 0-3 files | ~10-15% (small) |
|
||||
| 4-6 files | ~20-30% (medium) |
|
||||
| 7+ files | ~40%+ (large - split) |
|
||||
|
||||
**Rough heuristics for plan size:**
|
||||
| Complexity | Context/Task |
|
||||
|------------|--------------|
|
||||
| Simple CRUD | ~15% |
|
||||
| Business logic | ~25% |
|
||||
| Complex algorithms | ~40% |
|
||||
| Domain modeling | ~35% |
|
||||
|
||||
<file_counts>
|
||||
- 0-3 files modified: Small task (~10-15% context)
|
||||
- 4-6 files modified: Medium task (~20-30% context)
|
||||
- 7+ files modified: Large task (~40%+ context) - split this
|
||||
</file_counts>
|
||||
|
||||
<complexity>
|
||||
- Simple CRUD: ~15% per task
|
||||
- Business logic: ~25% per task
|
||||
- Complex algorithms: ~40% per task
|
||||
- Domain modeling: ~35% per task
|
||||
</complexity>
|
||||
|
||||
<two_task_plan>
|
||||
- 2 simple tasks: ~30% total ✅ Plenty of room
|
||||
- 2 medium tasks: ~50% total ✅ At target
|
||||
- 2 complex tasks: ~80% total ❌ Too tight, split
|
||||
</two_task_plan>
|
||||
|
||||
<three_task_plan>
|
||||
- 3 simple tasks: ~45% total ✅ Good
|
||||
- 3 medium tasks: ~75% total ⚠️ Pushing it
|
||||
- 3 complex tasks: 120% total ❌ Impossible, split
|
||||
|
||||
**Conservative principle:** When in doubt, split. Better to have an extra plan than degraded quality.
|
||||
</three_task_plan>
|
||||
**2 tasks:** Simple ~30%, Medium ~50%, Complex ~80% (split)
|
||||
**3 tasks:** Simple ~45%, Medium ~75% (risky), Complex 120% (impossible)
|
||||
</estimating_context>
|
||||
|
||||
<atomic_commits>
|
||||
|
||||
**What we're optimizing for:** Beautiful git history where each commit is:
|
||||
- Focused (2-3 related changes)
|
||||
- Complete (fully implemented, tested)
|
||||
- Documented (clear commit message)
|
||||
- Reviewable (small enough to understand)
|
||||
- Revertable (surgical rollback possible)
|
||||
|
||||
**Bad git history (large plans):**
|
||||
```
|
||||
feat(auth): Complete authentication system
|
||||
- Added 16 files
|
||||
- Modified 8 files
|
||||
- 1200 lines changed
|
||||
- Contains: models, API, UI, middleware, utilities
|
||||
```
|
||||
|
||||
Impossible to review, hard to understand, can't revert without losing everything.
|
||||
|
||||
**Good git history (atomic plans):**
|
||||
```
|
||||
feat(auth-01): Add User and Session database models
|
||||
- Added schema files
|
||||
- Added migration
|
||||
- 45 lines changed
|
||||
|
||||
feat(auth-02): Implement register and login API endpoints
|
||||
- Added /api/auth/register
|
||||
- Added /api/auth/login
|
||||
- Added JWT utilities
|
||||
- 120 lines changed
|
||||
|
||||
feat(auth-03): Add protected route middleware
|
||||
- Added middleware/auth.ts
|
||||
- Added tests
|
||||
- 60 lines changed
|
||||
|
||||
feat(auth-04): Build login and registration forms
|
||||
- Added LoginForm component
|
||||
- Added RegisterForm component
|
||||
- 90 lines changed
|
||||
```
|
||||
|
||||
Each commit tells a story. Each is reviewable. Each is revertable. This is craftsmanship.
|
||||
</atomic_commits>
|
||||
|
||||
<quality_assurance>
|
||||
|
||||
**The guarantee:** When you follow the 2-3 task rule with 50% context target:
|
||||
|
||||
1. **Consistency:** First task has same quality as last task
|
||||
2. **Thoroughness:** No "I'll complete X concisely" degradation
|
||||
3. **Documentation:** Full context budget for comments/tests
|
||||
4. **Error handling:** Space for proper validation and edge cases
|
||||
5. **Testing:** Room for comprehensive test coverage
|
||||
|
||||
**The cost:** More plans to manage.
|
||||
|
||||
**The benefit:** Consistent excellence. No rework. Clean history. Maintainable code.
|
||||
|
||||
**The trade-off is worth it.**
|
||||
</quality_assurance>
|
||||
|
||||
<summary>
|
||||
|
||||
**2-3 tasks, 50% context target:**
|
||||
- All tasks: Peak quality
|
||||
- Git: Atomic, surgical commits
|
||||
- Quality: Consistent excellence
|
||||
- Autonomous plans: Subagent execution (fresh context)
|
||||
|
||||
**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
|
||||
|
||||
Reference in New Issue
Block a user