long_task_planning v1.0.0

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.