fix(planning): never overwrite an incomplete plan without asking (#518)

When /plan runs for new work while tasks/plan.md and tasks/todo.md
still hold unchecked tasks, the agent silently replaces them,
destroying the in-flight plan's state (reported in #518).

Add a convention-neutral guard: replanning the same work updates in
place; different work stops and asks the user before touching the
existing files. Mirror the rule for external task list targets (no
bulk-closing another plan's items), and add matching Rationalization,
Red Flag, and Verification entries plus the guard line in the /plan
command.

Deliberately does not introduce a parallel-lane layout — that
convention decision is being held open in #518; this fixes only the
data-loss half.
This commit is contained in:
ayobamiseun committed 2026-08-28 16:54:48 +01:00
1 parent df1edb2e05
commit 8300e1bbe7
2 files changed
+12

No files matched your search

+2
View File
@@ -14,3 +14,5 @@ Read the existing spec (SPEC.md or equivalent) and the relevant codebase section
6. Present the plan for human review
Save the plan to tasks/plan.md and task list to tasks/todo.md.
If tasks/plan.md or tasks/todo.md already exists with unchecked tasks for different work, stop and ask before writing — never silently overwrite an incomplete plan.
@@ -147,6 +147,13 @@ If a task is L or larger, it should be broken into smaller tasks. An agent perfo
Create the `tasks/` directory if it does not exist.
**Never overwrite an incomplete plan.** Before writing `tasks/plan.md` or `tasks/todo.md`, check whether they already exist and still contain unchecked tasks:
- Same work being replanned (the user asked to revise or extend this plan) → update the existing files in place.
- Different work → **stop and ask.** The unchecked tasks may be mid-build in another session. Do not delete, overwrite, or rename the existing files on your own; present the conflict and let the user decide (finish the old plan first, explicitly discard it, or tell you where the new plan should go).
The same rule applies to an external task list target: never bulk-close or delete another plan's open tracker items to make room for new ones.
### Task List Target
The task list target is where tasks and checkpoints are recorded. It is defined once, here; every other reference in this skill defers to it.
@@ -219,10 +226,12 @@ When multiple agents or sessions are available:
| "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
| "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. |
| "The old `tasks/plan.md` is stale, I'll just replace it" | Unchecked tasks may be mid-build in another session. Overwriting them destroys work state that exists nowhere else. Stop and ask. |
## Red Flags
- Starting implementation without a written task list
- Overwriting a `tasks/plan.md` or `tasks/todo.md` that still has unchecked tasks for different work, without asking
- Writing `tasks/todo.md` when the project has designated an external tracker (or scattering tasks across both)
- Tasks that say "implement the feature" without acceptance criteria
- No verification steps in the plan
@@ -238,6 +247,7 @@ Before starting implementation, confirm:
- [ ] Every task has a verification step
- [ ] Task dependencies are identified and ordered correctly
- [ ] Tasks are recorded in the task list target (default `tasks/todo.md`)
- [ ] No pre-existing incomplete plan was overwritten without explicit user confirmation
- [ ] No task touches more than ~5 files
- [ ] Checkpoints exist between major phases
- [ ] The human has reviewed and approved the plan