| name | deep-work |
| description | Run a large, multi-place task as a checkpointed state machine over the runs store — plan, adversarial plan review, wave-by-wave execution, synthesis — one step per invocation, resumable after any interruption. Trigger: cross-file refactor, data migration, large feature build, multi-source research — work that cannot finish in one pass. Manual invocation: /deep-work. |
deep-work — a state machine over run-state
A deep-work run is rows, not memory: a runs row plus one run_steps row per step
in .taskmanager/taskmanager.db, with one brief file per step at
.taskmanager/runs/<run-id>/step-<seq>-<name>.md. The window holds nothing; resume,
crash recovery, and post-compaction pickup are all the same query. Store spec:
docs/architecture/runtime-state.md (schema v5, v_next_step, checkpoint rules).
Entry conditions (counted, not felt)
Run deep-work when ANY row fires; no row fired → /implement handles it directly.
| Countable | Threshold |
|---|
| files the task will touch (glob/grep its nouns) | > 5 |
| estimated LOC (sum of per-file estimates) | > 200 |
| acceptance criteria on the ask | > 4 |
| distinct top-level dirs touched | > 2 |
An audit / production-readiness ask is not deep-work — run deep-analysis.
The step machine
The plan step inserts the execute-<k> and synthesize rows and writes every
brief; execution order is run_steps.seq, served by v_next_step.
Invariant rules (always in force)
- One step per invocation. Read the step's phase file and its brief; execute;
checkpoint; only then query
v_next_step again. Never read ahead to other steps;
never load two phase files at once.
- Every step opens with the re-orientation preamble (fixed text in each phase
file): the brief is the complete truth; read ONLY what its attention contract
names; files win over memory.
- Checkpoint order: artifacts to disk → the step's
run_steps row
(status, artifacts_json, notes) → runs.current_step. The DB may lag disk,
never lead it.
- A failed step halts the run —
v_next_step returns no row for it, by
construction. Never silently retry in the same window; a step retried ×2 across
windows escalates per docs/architecture/escalation-ladder.md row 8.
- Parallelism is decided at plan time by the wave table in phase-1 — counted
from the subtasks' file lists, never from a feel for "large enough".
- The board lives in the store. Step notes go in
run_steps.notes; anything
larger is a disk artifact listed in artifacts_json. No thoughts/ directory
(retired — see skills/thoughts/SKILL.md).
Preflight
No .taskmanager/ → run taskmanager:init first. runs table absent (schema <
v5) → stop and name the migration per docs/architecture/runtime-state.md
(migrate-v4.2-to-v5.sh); never emulate the store with files.
