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

<scope_estimation> Plans must maintain consistent quality from first task to last. This requires understanding quality degradation and splitting aggressively.

<quality_insight> Claude 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

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.

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%?

• No context anxiety possible
• Quality maintained start to finish
• Room for unexpected complexity
• 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.

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

<tdd_plans> TDD features get their own plans. Target ~40% context.

TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than linear task execution.

TDD Feature Complexity	Context Usage
Simple utility function	~25-30%
Business logic with edge cases	~35-40%
Complex algorithm	~40-50%

One feature per TDD plan. If features are trivial enough to batch, they're trivial enough to skip TDD.

Why TDD plans are separate:

• TDD consumes 40-50% context for a single feature
• Dedicated plans ensure full quality throughout RED-GREEN-REFACTOR
• Each TDD feature gets fresh context, peak quality

See ~/.claude/get-shit-done/references/tdd.md for TDD plan structure. </tdd_plans>

<split_signals>

<always_split>

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

• 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 dependency: Payments → 01: Stripe setup, 02: Subscription logic, 03: Frontend integration

By complexity: Dashboard → 01: Layout shell, 02: Data fetching, 03: Visualization

By verification: Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint) </splitting_strategies>

<parallel_aware_splitting> When parallelization is enabled, optimize for plan independence.

<philosophy_shift>

Aspect	Sequential Planning	Parallel-Aware Planning
Grouping	By workflow stage	By vertical slice
Dependencies	Implicit (later plans reference earlier)	Explicit (only when genuinely needed)
File ownership	Overlap acceptable	Exclusive where possible
SUMMARY refs	Chain pattern (02 refs 01, 03 refs 02)	Minimal (only for real data deps)
Wave result	Most plans in Wave 2+	More plans in Wave 1
</philosophy_shift>

<vertical_slice_example> Sequential (creates chain):

Plan 01: Create User model, Product model, Order model
Plan 02: Create /api/users, /api/products, /api/orders
Plan 03: Create UserList UI, ProductList UI, OrderList UI

Result: 02 depends on 01 (needs models), 03 depends on 02 (needs APIs) Waves: [01] → [02] → [03] (fully sequential)

Parallel-aware (creates independence):

Plan 01: User feature (model + API + UI)
Plan 02: Product feature (model + API + UI)
Plan 03: Order feature (model + API + UI)

Result: Each plan self-contained, no file overlap Waves: [01, 02, 03] (all parallel) </vertical_slice_example>

<when_to_restructure> Restructure for vertical slices when:

• Phase has 3+ features that are independent
• No shared infrastructure requirements
• Each feature touches different files
• Features can be tested independently

Keep sequential when:

• Genuine data dependencies (Order needs User type)
• Shared foundation required (auth setup before protected features)
• Single feature being built incrementally
• Phase is already a vertical slice </when_to_restructure>

<file_ownership> Explicit file ownership prevents conflicts:

# Plan 01 frontmatter
files_exclusive: [src/models/user.ts, src/api/users.ts, src/components/UserList.tsx]

# Plan 02 frontmatter
files_exclusive: [src/models/product.ts, src/api/products.ts, src/components/ProductList.tsx]

If file appears in multiple plans: Later plan depends on earlier (by plan number). If file cannot be split: Plans must be sequential for that file. </file_ownership>

<summary_references> Minimize SUMMARY references when parallel-aware:

Before (sequential habit):

<context>
@.planning/phases/05-features/05-01-SUMMARY.md  # Always reference prior
@.planning/phases/05-features/05-02-SUMMARY.md  # Chain continues
</context>

After (parallel-aware):

<context>
# Only reference if this plan ACTUALLY needs decisions from prior plan
# Most parallel plans don't need any SUMMARY references
</context>

Include SUMMARY only when:

• Prior plan made a decision that affects this plan's approach
• Prior plan created types/interfaces this plan imports
• Prior plan's output is input to this plan </summary_references> </parallel_aware_splitting>

<anti_patterns> Bad - Comprehensive plan:

Plan: "Complete Authentication System"
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

Good - Atomic plans:

Plan 1: "Auth Database Models" (2 tasks)
Plan 2: "Auth API Core" (3 tasks)
Plan 3: "Auth API Protection" (2 tasks)
Plan 4: "Auth UI Components" (2 tasks)
Each: 30-40% context, peak quality, atomic commits (2-3 task commits + 1 metadata commit)

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

Complexity	Context/Task
Simple CRUD	~15%
Business logic	~25%
Complex algorithms	~40%
Domain modeling	~35%

2 tasks: Simple ~30%, Medium ~50%, Complex ~80% (split) 3 tasks: Simple ~45%, Medium ~75% (risky), Complex 120% (impossible) </estimating_context>

<depth_calibration> Depth controls compression tolerance, not artificial inflation.

Depth	Typical Phases	Typical Plans/Phase	Tasks/Plan
Quick	3-5	1-3	2-3
Standard	5-8	3-5	2-3
Comprehensive	8-12	5-10	2-3

Tasks/plan is CONSTANT at 2-3. The 50% context rule applies universally.

Key principle: Derive from actual work. Depth determines how aggressively you combine things, not a target to hit.

• Comprehensive auth = 8 plans (because auth genuinely has 8 concerns)
• Comprehensive "add favicon" = 1 plan (because that's all it is)

Don't pad small work to hit a number. Don't compress complex work to look efficient.

Comprehensive depth example: Auth system at comprehensive depth = 8 plans (not 3 big ones):

• 01: DB models (2 tasks)
• 02: Password hashing (2 tasks)
• 03: JWT generation (2 tasks)
• 04: JWT validation middleware (2 tasks)
• 05: Login endpoint (2 tasks)
• 06: Register endpoint (2 tasks)
• 07: Protected route patterns (2 tasks)
• 08: Auth UI components (3 tasks)

Each plan: fresh context, peak quality. More plans = more thoroughness, same quality per plan. </depth_calibration>

**2-3 tasks, 50% context target:** - All tasks: Peak quality - Git: Atomic per-task commits (each task = 1 commit, plan = 1 metadata commit) - 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.

Depth rule: Depth increases plan COUNT, never plan SIZE.

Commit rule: Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit). More granular history = better observability for Claude.