---
name: long_task_planning
description: Run long multi-step tasks with file-based planning: set up plan, findings, and progress files at the start, checkpoint after each unit of work, detect stale plans, and recover when work drifts off course. Triggers on "long task", "multi-step project", "this will take several sessions", "pick up where I left off", "my plan drifted", or any job too big for one context window.
---

# Long-Task Planning

## Purpose
Keep a long, multi-step task on course across sessions, context compactions, and interruptions. The method: keep the plan, the findings, and the progress in files, not in your head. The context window is RAM, the filesystem is disk. Anything important goes to disk. Every claim about what is done must be checkable on disk.

## Workflow

### 1. Set up the plan directory (once per task)
Create `<task-dir>/` with three files:
- `PLAN.md`: the work broken into small units, each with a status line and a done-criterion. Statuses are only `todo`, `doing`, `done`, `blocked`. No other statuses.
- `FINDINGS.md`: facts learned along the way: decisions, gotchas, error logs, anything the next session needs so it does not re-discover it.
- `PROGRESS.md`: an append-only log. Every unit of work gets one entry: date, what changed, what was verified, what is next.

Keep each unit small enough to finish in one session. A unit whose done-criterion you cannot state is still two units.

### 2. Orient before touching anything (every session)
Read order, every time:
1. `PROGRESS.md` from the tail upward, enough to find where work stopped.
2. `PLAN.md`, to confirm which unit is marked `doing`.
3. `FINDINGS.md` relevant sections.
4. Verify against reality: check that the files the plan claims exist actually exist, and that anything claimed `done` still checks out. If the plan and reality disagree, reality wins: fix the plan first.

Never start work from memory of the plan. Memory is the most stale copy.

### 3. Work one unit, then checkpoint
Pick the highest-priority unit marked `doing` (or the first `todo`). Finish it, verify its done-criterion, then checkpoint before anything else:
1. Append the `PROGRESS.md` entry.
2. Flip the unit to `done` in `PLAN.md` (or `blocked`, with the blocker noted in FINDINGS.md).
3. If the task lives in git, commit. Commits are checkpoints with a built-in undo button.
4. Only then move to the next unit.

No batching: a crash between unit 2 and unit 3 must never lose unit 2's record.

### 4. Re-read the plan before major decisions
The classic failure: you write the plan, then keep working from your mental copy as it goes stale. Force a re-read of `PLAN.md` before any decision that changes scope, tools, or direction. If the decision invalidates part of the plan, rewrite that part of the plan before implementing.

### 5. Stale-plan detection (run at least daily on long tasks)
A plan is stale when it no longer describes reality. Check with `bin/plan_doctor.py <task-dir>` or by hand:
- A unit marked `done` whose done-criterion no longer verifies on disk.
- A unit marked `doing` with no PROGRESS entry newer than 48 hours.
- FINDINGS or PLAN files edited after the last PROGRESS entry (planning without doing).
- Deadlines or assumptions in the plan that have silently expired.

When stale, repair: re-verify each claimed-done unit, flip wrong ones back to `todo`, rewrite dead assumptions, and log the repair in PROGRESS.md.

### 6. Recovery when work drifts off course
Drift means the work moved but the plan did not, or the plan moved but the work did not. Signs: you cannot find where you stopped, two sessions redo the same work, or completed work contradicts the plan. Recovery:
1. Freeze: stop doing new work.
2. Audit: walk PLAN.md top to bottom and re-verify each unit against disk, flipping statuses to match reality.
3. Rewrite the bad part of the plan as a fresh, smaller sequence of units.
4. Log the audit in PROGRESS.md: what drifted, what you changed, what unit is next.
Detailed playbooks live in `references/recovery-playbooks.md`.

## Output Contract
- A task dir with `PLAN.md`, `FINDINGS.md`, `PROGRESS.md`, written before real work begins.
- Every unit of work leaves one PROGRESS entry and one PLAN status flip, made before the next unit starts.
- A `blocked` unit always names the blocker and where it is documented.
- A drift or stale-plan event always ends with a PROGRESS entry naming what changed.

## Operating Rules
1. Disk is truth. A claim in the plan means nothing until it verifies on disk.
2. Append-only memory: log new entries, never rewrite history. If you must correct the record, add an entry that says the old one was wrong.
3. `todo` means not started. `doing` means exactly one unit at a time. `done` means verified against its done-criterion, not just attempted.
4. Plans are per-task files, not chat summaries. If the plan only exists in a conversation, there is no plan.
5. When a session can read and verify the three files in under a few minutes, the plan is good. If onboarding takes longer than the first unit, the plan is too complex and must be simplified.
6. This skill pairs with, not replaces: `agent-task-decomposition` for splitting the work before the run, `long-term-planning` for dated human-facing roadmaps.