planning-with-files

## Core Principle

```
Context Window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)
→ Anything important MUST be written to disk.
```

## When to Use

- Multi-step tasks (3+ phases or 5+ tool calls)
- Research + implementation tasks
- Tasks that span multiple sessions
- Any task where goal-drift is a risk

Skip for: single-file edits, quick lookups, simple questions.

## Session Start Protocol

**ALWAYS do this first — no exceptions:**

1. Run the init script to create the three planning files:
   ```
   exec: bash {baseDir}/scripts/init-session.sh "<task description>"
   ```
2. Fill in the `## Goal` section in `task_plan.md` with the full task description.
3. Break the task into 3–7 phases and add them under `## Phases`.
4. Confirm files exist before proceeding.

If exec is not available, create the three files manually using the templates in `{baseDir}/templates/`.

## The Three Files

### task_plan.md — Goal tracker (MOST IMPORTANT)
- Created at session start, never deleted
- Re-read before every major decision
- Update when: phase completes, decision made, error encountered

### findings.md — Knowledge store
- Research results, discoveries, technical decisions
- **2-Action Rule**: after every 2 view/search/fetch operations → update findings.md immediately

### progress.md — Session log
- Actions taken, test results, errors encountered
- Append-only; never rewrite history

## Work Loop

```
BEFORE every major action:
  → Re-read task_plan.md (keeps goal in attention)

EVERY 2 view/search/fetch operations:
  → Save key findings to findings.md NOW

AFTER completing a phase:
  → Update phase status in task_plan.md to "complete"
  → Append phase summary to progress.md

WHEN an error occurs:
  → Log it in task_plan.md under ## Errors table
  → Never repeat the same failing action

BEFORE stopping:
  → Run: exec bash {baseDir}/scripts/check-complete.sh
  → Only stop if all phases show "complete"
```

## File Update Rules

| Trigger | File to update | Section |
|---------|---------------|---------|
| Start task | task_plan.md | Goal + Phases |
| 2nd research op | findings.md | Key Findings |
| Make decision | findings.md | Technical Decisions |
| Phase done | task_plan.md | Phase status → complete |
| Phase done | progress.md | Phase summary |
| Error | task_plan.md | Errors table |
| Test result | progress.md | Test Results |

## Error Recovery Protocol

```
ATTEMPT 1: Diagnose & Fix
  → Read error carefully → identify root cause → targeted fix

ATTEMPT 2: Alternative Approach
  → Same error? Try different tool/library/method
  → NEVER repeat the exact same failing action

ATTEMPT 3: Broader Rethink
  → Question assumptions → search for solutions → update plan

AFTER 3 FAILURES:
  → Escalate to user: explain what was tried, share the error, ask for guidance
```

## Completion Verification

Before telling the user the task is done:
1. Run `exec bash {baseDir}/scripts/check-complete.sh`
2. If any phase is NOT "complete" → continue working
3. Only deliver result when all phases are checked off

## Session Recovery

If context was cleared (e.g., `/clear`), resume by:
1. Reading `task_plan.md` to restore goal and phase status
2. Reading `progress.md` to see what was done
3. Reading `findings.md` to restore research context
4. Continuing from the first incomplete phase

## Key Principles

- **Plan is Required**: Never start a complex task without `task_plan.md`
- **Files are Memory**: Context is volatile. Filesystem is permanent. Write important things down.
- **Never Repeat Failures**: Track what was tried. Mutate the approach.
- **Error Recovery = Agentic Behavior**: How you handle failures defines task quality.
- **Re-read Before Deciding**: Attention manipulation — keep the goal visible.