msd-core/get-shit-done/references/scope-estimation.md

<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.

<quality_degradation_curve>

**Critical insight:** Claude doesn't degrade at arbitrary percentages - it degrades when it *perceives* context pressure and enters "completion mode."

```
Context Usage  │  Quality Level   │  Claude's Mental State
─────────────────────────────────────────────────────────
0-30%          │  ████████ PEAK   │  "I can be thorough and comprehensive"
               │                  │  No anxiety, full detail, best work

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>

<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
- 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.
</context_target>

<task_rule>

**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

**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
</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
</consider_splitting>
</split_signals>

<splitting_strategies>

<by_subsystem>

**Phase:** "Authentication System"

**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>
</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>

```
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
```

**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>

```
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
```

**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>

**Rough heuristics for plan size:**

<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>
</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.

**The rule:** If in doubt, split. Quality over consolidation. Always.
</summary>
</scope_estimation>