planning

# Planning in Small Increments

**All work must be done in small, known-good increments.** Each increment leaves the codebase in a working state where all tests pass.

**Document Management**:
- Long-term plan: `localdocs/plan.<topic>.md`
- Future (not yet planned): `localdocs/backlog.<topic>.md`
- Execution logs: `worklog` skill (`localdocs/worklog.todo.md`, `localdocs/worklog.doing.md`, `localdocs/worklog.done.md`)
- Learning notes: `localdocs/learn.<topic>.md`

## Usage Boundary

- Use this `planning` skill at planning time (before implementation starts).
- During implementation execution, use `progress-guardian` to track progress/learning snapshots and step-by-step status.
- During RED/GREEN/REFACTOR test loops, use `tdd-guardian`.

## Plan + Worklog + Learn Model

For significant work, maintain one long-term plan, worklog files, and a learning note:

| Document | Purpose | Lifecycle |
|----------|---------|-----------|
| **`localdocs/backlog.<topic>.md`** | Future ideas before planning | Optional, persistent |
| **`localdocs/plan.<topic>.md`** | What we're doing | Created at start, changes need approval |
| **`localdocs/worklog.todo.md`** | Pending phase/session tasks | Persistent |
| **`localdocs/worklog.doing.md`** | In-progress phase/session tasks | Persistent |
| **`localdocs/worklog.done.md`** | Completed phase/session log | Persistent |
| **`localdocs/learn.<topic>.md`** | Learning notes / gotchas / decisions | Scoped to a topic; merged into CLAUDE.md/ADR, kept as reference |

### Document Relationships

```
`localdocs/plan.<topic>.md` (static)          `worklog.todo/doing/done` (execution log)           `localdocs/learn.<topic>.md` (learning notes)
┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│ Goal            │       │ Current step    │       │ Gotchas         │
│ Acceptance      │  ──►  │ Status          │  ──►  │ Patterns        │
│ Steps 1-N       │       │ Blockers        │       │ Decisions       │
│ (approved)      │       │ Next action     │       │ Edge cases      │
└─────────────────┘       └─────────────────┘       └─────────────────┘
        │                         │                         │
        │                         │                         │
        └─────────────────────────┴─────────────────────────┘
                                  │
                                  ▼
                         END OF FEATURE
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
                    ▼                           ▼
              Keep worklog logs        Merge learnings into:
                                       - CLAUDE.md (`learn` agent)
                                       - ADRs (`adr` agent)
                                       Keep learn files as reference
```

## Phase 0: Pre-Implementation Interview

Before breaking work into increments, you **MUST** complete three steps in order: declare the work stage, verify technical assumptions, then probe for implementation unknowns.

**This phase catches two sources of wasted effort:**
1. Requirements that seemed clear during PRD but reveal ambiguity at implementation time
2. Technical assumptions (compatibility, API behavior) that turn out to be wrong mid-implementation

### Step 0-A: Declare the Work Stage

Ask the user to declare the stage before anything else. If already stated, confirm it.

| Stage | Plan depth | Code quality | Exit criteria |
|-------|-----------|--------------|---------------|
| **SPIKE** | Hypothesis + exit criteria only | Working only | Hypothesis pass/fail confirmed |
| **MVP** | Core flow + key edge cases | Basic test coverage | Core user scenario passes |
| **PROD** | Full spec (clients, compatibility) | TDD + docs | Deployable quality |

**If stage is SPIKE:**
- Capture: "Hypothesis: [what we're testing]" and "Exit criteria: [what pass/fail looks like]"
- Add `# SPIKE: [hypothesis] — delete after validation` comment to all SPIKE code
- SPIKE code must NOT be promoted to PROD directly — rewrite at MVP stage

**If no stage is declared, default to PROD.**

### Step 0-B: Technical Feasibility Check

Before the interview, use WebSearch to verify any external dependency the plan will rely on. **Do not rely on training knowledge for fast-moving ecosystems.**

**Always verify when the work involves:**
- External APIs or third-party services → confirm auth method, endpoint schema, rate limits
- Multiple clients or platforms → confirm compatibility across all targets (web/mobile/desktop/CLI)
- Library or framework features → confirm the feature exists in the project's current version
- Known-tricky domains → search "[library] [feature] issues [year]" to surface gotchas

**Output**: Before the interview begins, state:
```
Verified: [what was confirmed via search, with source]
Unverified / TBD: [what couldn't be confirmed — flag as risk in plan]
```

If verification reveals a blocker or significant risk, surface it before proceeding to the interview.

### Step 0-BDD: Requirements Specification (MVP / PROD only)

With stage declared and assumptions verified, clarify *what* to build before addressing *how*.

**Stage branching:**

| Stage | grill-me | user-story.md | BDD pytest |
|-------|----------|---------------|------------|
| SPIKE | ✅ questions only | ❌ | ❌ |
| Architecture | ✅ questions only | ❌ | ❌ |
| MVP | ✅ | ✅ user writes | ✅ user writes |
| PROD | ✅ | ✅ user writes | ✅ user writes |

**Execution — SPIKE / Architecture:**

Run `grill-me` to reach shared understanding. Stop when the user confirms no more open questions. No written artifacts required.

**Execution — MVP / PROD:**

1. **Step 1 — grill-me**: Use the `grill-me` skill to probe requirements until shared understanding is reached.
2. **Step 2 — user writes `localdocs/user-story.*.md`**: Wait for the user to write the file. Do not write it for them.
3. **Step 3 — user writes BDD pytest file in `tests/`**: Wait for the user to write failing tests. Do not generate them.
4. **Step 4 — reference in plan**: When creating `localdocs/plan.<topic>.md`, explicitly name the `user-story.*.md` file in the Goal section.

**Claude behavior rules during Phase 0-BDD:**

❌ Do NOT:
- Generate code of any kind
- Write `user-story.*.md` directly
- Present a complete given/when/then scenario
- Generate the BDD pytest file

✅ DO:
- Ask questions using `grill-me` style
- Provide one sample or a partial skeleton *only if the user explicitly asks before starting to write*
  - Option A: one complete test as reference (one only)
  - Option B: empty skeleton (function signature + comments, no body)

The user types "이제 쓸게" or equivalent → switch immediately to waiting mode.

**Bypass:** If the user types exactly `삐약삐약 저는 코딩 병아리입니다.` (lit. "Cheep cheep, I'm a coding chick.") in the chat, grill-me still runs as normal, but Claude generates the complete `user-story.*.md` and BDD pytest file directly instead of waiting for the user to write them.

---

### Step 0-C: Implementation Interview

With stage declared, technical assumptions verified, and requirements specified, probe for implementation-specific unknowns. Use `AskUserQuestion`.

**When to run this interview:**
- Always, before creating `localdocs/plan.<topic>.md`
- Even if a PRD exists — PRDs cover *what*, this covers *how*

**Interview Protocol:**

1. **Read all available context first.** PRD, existing code, related docs. Form your own mental model before asking.
2. **Ask questions the user hasn't thought about yet.** Don't repeat PRD questions. Focus on implementation-specific unknowns.
3. **2-3 rounds minimum.** Each round should surface new concerns. Stop only when the user confirms no more unknowns.
4. **Document answers in the plan file.** Captured decisions prevent future "wait, I thought we agreed..." moments.

**Interview Dimensions (implementation-focused):**

- **Data Shape**: What does the actual data look like? Sample inputs/outputs? Null/empty cases?
- **State Transitions**: What states exist? What transitions are valid? What happens on invalid transitions?
- **Error Scenarios**: What can go wrong? What does the user see? Retry? Fail silently? Alert?
- **Performance Boundaries**: Expected data volume? Concurrent users? Acceptable latency?
- **Existing Code Impact**: What existing behavior changes? What must NOT change?
- **Testing Strategy**: How do we test this? What mocks are needed? What's hard to test?
- **Deployment Concerns**: Feature flag? Migration needed? Backward compatibility?

**Anti-Patterns:**

- ❌ Skipping the interview because "the PRD is detailed enough"
- ❌ Asking generic questions instead of project-specific ones
- ❌ Starting increments before the user confirms "the approach makes sense"
- ❌ Treating this as a formality — if answers don't change your plan, you asked the wrong questions
- ❌ Skipping Step 0-B because "it's a well-known library" — that's exactly when version gaps appear
- ❌ Promoting SPIKE code to PROD without rewriting at MVP stage

---

## What Makes a "Known-Good Increment"

Each step MUST:
- Leave all tests passing
- Be independently deployable
- Have clear done criteria
- Fit in a single commit
- Be describable in one sentence

**If you can't describe a step in one sentence, break it down further.**

## Step Size Heuristics

**Too big if:**
- Takes more than one session
- Requires multiple commits to complete
- Has multiple "and"s in description
- You're unsure how to test it
- Involves more than 3 files

**Right size if:**
- One clear test case
- One logical change
- Can explain to someone in 30 seconds
- Obvious when done
- Single responsibility

## TDD Integration

**Every step follows RED-GREEN-REFACTOR.**

```
FOR EACH STEP:
    │
    ├─► RED: Write failing test FIRST
    │   - Test describes expected behavior
    │   - Test fails for the right reason
    │
    ├─► GREEN: Write MINIMUM code to pass
    │   - No extra features
    │   - No premature optimization
    │   - Just make the test pass
    │
    ├─► REFACTOR: Assess improvements
    │   - See `refactoring` skill
    │   - Only if it adds value
    │   - All tests still pass
    │
    └─► STOP: Wait for commit approval
```

**No exceptions. No "I'll add tests later."**

## Commit Discipline

**NEVER commit without user approval.**

After completing a step (RED-GREEN-REFACTOR):

1. Verify all tests pass
2. Verify static analysis passes
3. Update `localdocs/worklog.doing.md` with progress
4. Move task states with `worklog` skill (`todo` → `doing` → `done`)
5. Capture knowledge learnings in `localdocs/learn.<topic>.md` when discovered
6. **STOP and ask**: "Ready to commit [description]. Approve?"

Only proceed with commit after explicit approval.

### Why Wait for Approval?

- User maintains control of git history
- Opportunity to review before commit
- Prevents accidental commits of incomplete work
- Creates natural checkpoint for discussion

## `localdocs/plan.<topic>.md` Structure

```markdown
# Plan: [Feature Name]

## Goal

[One sentence describing the outcome]

**User story reference**: `localdocs/user-story.<topic>.md` *(MVP/PROD only — omit for SPIKE)*

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Steps

### Step 1: [One sentence description]

**Test**: What failing test will we write?
**Implementation**: What code will we write?
**Done when**: How do we know it's complete?

### Step 2: [One sentence description]

**Test**: ...
**Implementation**: ...
**Done when**: ...
```

### Plan Changes Require Approval

If the plan needs to change:

1. Explain what changed and why
2. Propose updated steps
3. **Wait for approval** before proceeding

Plans are not immutable, but changes must be explicit and approved.

## `worklog` Structure

Use the `worklog` skill as the source of truth for:
- `localdocs/worklog.todo.md`
- `localdocs/worklog.doing.md`
- `localdocs/worklog.done.md`

Do not maintain separate manual templates for these files in planning docs.

### Progress Snapshot Must Always Be Accurate

Update `localdocs/worklog.doing.md`:
- When starting a new step
- When status changes (RED → GREEN → REFACTOR)
- When blockers appear or resolve
- After each commit
- At end of each session

**If `localdocs/worklog.doing.md` doesn't reflect reality, update it immediately.**

## `localdocs/worklog.done.md`

Append-only execution history grouped by date. Update via `worklog done ...`.

### Capture Execution Logs As They Occur

Don't wait until the end. When you discover something:

1. Record task completion in `localdocs/worklog.done.md` via `worklog done ...`
2. Continue with current work
3. At end of feature, use this as execution history only

## `localdocs/learn.<topic>.md` Structure

```markdown
# Learnings: [Feature Name]

## Gotchas
- [What happened and why]

## Patterns
- [What worked and when to apply]

## Decisions
- [Decision + rationale + trade-offs]
```

## End of Feature

When all steps are complete:

1. Verify all acceptance criteria met and tests passing
2. Merge learnings: `learn` agent (gotchas/patterns → CLAUDE.md), `adr` agent (decisions → ADR)
3. Remove only `localdocs/plan.<topic>.md` (keep worklog and learn files)

## Anti-Patterns

❌ **Committing without approval**
- Always wait for explicit "yes" before committing

❌ **Steps that span multiple commits**
- Break down further until one step = one commit

❌ **Writing code before tests**
- RED comes first, always

❌ **Letting `localdocs/worklog.doing.md` become stale**
- Update immediately when reality changes

❌ **Confusing worklog and learning docs**
- Worklog tracks execution; `learn`/`adr` capture lasting knowledge

❌ **Putting future ideas directly into plan**
- If not in current approved scope, record first in `localdocs/backlog.<topic>.md`

❌ **Plans that change silently**
- All plan changes require discussion and approval

❌ **Deleting worklog files**
- Worklog files are persistent logs and should remain

## Quick Reference

```
START FEATURE
│
├─► Phase 0-A: Declare stage (SPIKE / MVP / PROD)
│   └─► If SPIKE: capture hypothesis + exit criteria
├─► Phase 0-B: Technical feasibility check (WebSearch)
│   └─► State verified / unverified assumptions before proceeding
├─► Phase 0-BDD: Requirements specification
│   ├─► [SPIKE/Architecture] grill-me questions → shared understanding only
│   └─► [MVP/PROD]
│       ├─► grill-me questions until no open requirements
│       ├─► user writes localdocs/user-story.*.md
│       ├─► user writes tests/test_*.py (BDD failing tests)
│       └─► (Claude waits — does NOT generate these artifacts)
├─► Phase 0-C: Pre-implementation interview (AskUserQuestion)
│   └─► Continue until no new unknowns emerge
├─► Create `localdocs/plan.<topic>.md` with user-story ref (get approval)
├─► worklog todo  ← each step from the plan
├─► worklog doing ← first step (do this immediately, without waiting to be asked)
│
│   FOR EACH STEP:
│   │
│   ├─► RED: Failing test
│   ├─► GREEN: Make it pass
│   ├─► REFACTOR: If valuable
│   ├─► worklog done  ← completed step (do this immediately when done)
│   ├─► worklog doing ← next step    (do this immediately after done)
│   └─► **WAIT FOR COMMIT APPROVAL**
│
END FEATURE
│
├─► Verify all criteria met
├─► Merge learnings (learn agent, adr agent)
└─► Close/remove only `localdocs/plan.<topic>.md` (keep worklog files)
```

## Worklog Automation Rule

Call `worklog` automatically — do not wait for the user to ask.

| Moment | Command |
|--------|---------|
| Plan approved, first step starts | `worklog todo [step2], [step3], ...` then `worklog doing [step1]` |
| Step completes (tests pass) | `worklog done [step]` |
| Next step begins | `worklog doing [next step]` |
| Blocker appears | Update `worklog.doing.md` directly with blocker note |
| Session ends | Ensure `worklog.doing.md` reflects current reality |