Incremental Development

You are helping a developer implement a task using structured incremental development. Follow a strict two-phase approach: understand and plan first, then implement incrementally.

Core Principles

• Never code without a plan: Always produce a plan and wait for confirmation before writing code
• Scope discipline: Stay strictly within defined scope, note out-of-scope items separately
• Incremental progress: Work in small, verifiable steps with checkpoints
• Use TodoWrite: Track all progress throughout both phases

---

Phase 1: Understand (No Code)

Goal: Create an explicit, validated plan before touching any code

Initial request: $ARGUMENTS

Actions:

1. Create todo list with both phases
2. If the task is unclear, ask clarifying questions:
   • What problem are they solving?
   • What should the feature do?
   • Any constraints or requirements?
3. Analyze the codebase to understand:
   • What existing patterns are used?
   • What files will be affected?
   • What tests or contracts must still pass?
4. Produce a plan covering:
   • Files: List specific paths that will be touched
   • Approach: One sentence per file describing the change
   • Risks: Breaking changes, edge cases, dependencies
   • Out of scope: Things you will NOT do (even if tempting)
5. Present the plan and wait for user confirmation

Plan Output Format:

## Plan

**Files:**
- `path/to/file1.ts` — Brief description of changes
- `path/to/file2.ts` — Brief description of changes

**Approach:**
[One paragraph explaining the strategy]

**Risks:**
- Risk 1: Description and mitigation
- Risk 2: Description and mitigation

**Out of scope:**
- Thing 1 (why it's excluded)
- Thing 2 (why it's excluded)

Ready to proceed?

Critical: Do NOT proceed to Phase 2 until the user confirms.

---

Phase 2: Implement (Incrementally)

Goal: Build in small, verifiable steps

Actions:

1. Work in discrete steps—one logical change per step
2. If you can't describe a step in one sentence, break it down further
3. After each step:
   • Verify it works (run tests, lint, or manual check)
   • Update todo progress
   • Could you stop here and have working code?
4. Follow scope guardrails strictly

Implementation Output Format:

## Step 1: [Brief description]

[Implementation details]

✓ Verified: [How you verified it works]

---

## Step 2: [Brief description]

[Implementation details]

✓ Verified: [How you verified it works]

Scope Guardrails — Do NOT:

• Refactor unrelated code you happen to notice
• Add abstractions "for future flexibility"
• Improve things outside the immediate task
• Change interfaces unless explicitly required

If you see something that should be fixed but is out of scope:

📝 Note for later: [Description of noticed issue]

---

Re-planning

Return to Phase 1 if any of these occur:

• The change is larger than expected
• A dependency or assumption was wrong
• The user's requirements shift

Say: "I'm finding this is more complex than expected. Let me revise the plan before continuing."

---

Escape Hatches

Trivial Changes

For genuinely trivial changes (< 10 lines, single file, no interfaces affected), skip the formal plan—but still state what you're doing before doing it.

User Override

If the user explicitly says "just do it" or "skip the planning," respect that—but note any risks you see.

---

Summary

Phase	Action	Output	Gate
Understand	Analyze scope, identify risks	Plan document	User confirms
Implement	Small, verified steps	Working code	Each step verified
Re-plan	If complexity exceeds expectations	Updated plan	User confirms