Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan/resume

deepworkplan-resume

Verified

Resume interrupted Lite or Full Deep Work Plans from durable Markdown and state, including safe recovery of promotions without duplicating completed work or gates.

FileKindSize
SKILL.mdskill md19.0 KB
v6.mdmarkdown4.3 KB
---
name: deepworkplan-resume
description: Resume interrupted Lite or Full Deep Work Plans from durable Markdown and state, including safe recovery of promotions without duplicating completed work or gates.
version: "7.8.1"
documentation_url: https://deepworkplan.com
user-invocable: true
allowed-tools: Bash, Read, Grep, Glob, Edit, Write
---

# DeepWorkPlan — Resume

Safely continue an interrupted plan from where it stopped — no duplicated work,
strict order, continuing from the first `[ ]` task — from **durable workspace
artifacts alone** (the plan folder on disk, gitignored `.dwp/` included): a
different session, agent, model or harness must be able to pick the plan up
without the previous conversation. A fresh clone without `.dwp/` has nothing
to resume — see *Persistence* below.

## Shared resources (read at their moment, not upfront)

The compulsory set for this flow is the router SKILL plus this file: every
rule the resumption assessment runs on is stated inline in Step 2 below. A
default resumption reads **no** guide, spec, shared companion, or execution
contract before assessment; each loads when its moment arrives. (This
ordering is deliberate: reading companions "to be safe" is the failure mode
this tiering removed.)

- **Essential now (before the first task):**
  [`../shared/context.sh`](../shared/context.sh) — **run** it
  (`bash ../shared/context.sh`) to resolve repo root, branch, agent tool and
  `dwp_dir`; its source is not part of this flow's reads. That is the whole
  t0 set — the resume protocol (Step 2) and the handoff rules are inline
  below.
- **Conditional — read only when the trigger fires:**
  - [`v6.md`](v6.md) (this directory) — read only when Step 2.0 detects a
    v6 plan: the v6 recovery ladder, cross-agent handoff and migration
    boundary. A v5 plan never reads it.
  - [`../spec/V6_LIFECYCLE.md`](../spec/V6_LIFECYCLE.md) — read only
    when a migration or cross-agent question goes beyond `v6.md` (§8–§9).
  - [`../execute/SKILL.md`](../execute/SKILL.md) — read only when Step 5
    resumes into the execution loop: the contract every resumed task runs
    under (gate selection, repair/stop, task-local closure, the Final
    Review). Assessment — Steps 1–4 — never needs it; once loaded, its own
    conditional tier governs its execution-time companions.
  - [`../spec/PLAN_STATE.md`](../spec/PLAN_STATE.md) §5–§6 — read only when
    the plan carries `state.json` and a desync, a takeover, or a standard
    question needs the normative rule; the everyday needs (markdown wins,
    regenerate from the README, the checkpoint shape) are inline in Step 2.
  - [`../guide/swarm.md`](../guide/swarm.md) §17 — read only when the plan
    holds a pending handoff packet (Step 2.0a) or a lead succession is in play.
  - [`../guide/prompts.md`](../guide/prompts.md) §9 — read only when the
    interruption is unusual enough that the Step 2.5 boundary table does not
    classify it (resume rules and scenarios).
  - [`../shared/dwp-paths.md`](../shared/dwp-paths.md) — read only when a
    plan folder cannot be located or the `DWP_DIR` override is in play
    (Steps 0–1 already inline `.dwp/plans/<plan>/`).
  - [`../shared/troubleshooting.md`](../shared/troubleshooting.md) — read
    only when something is already wrong (discovery failure, stale
    installation, missing test command, unsupported host capability,
    inconsistent plan state).
  - [`../guide/GUIDE.md`](../guide/GUIDE.md) — the routing index; consult
    only when a need is not covered by a section named above.
- **Never by default:** no other guide, spec, preset or addon file is read
  for this flow — not defensively, not "to be safe". `../shared/adaptation.md`
  and `../guide/execution.md` are not resume reads: their moments belong to
  execute/SKILL.md's tier once Step 5 loads it. Name the moment, then read.

## Parameter Support

- `/dwp-resume {plan_name}` — resume directly (skip the menu).
- `/dwp-resume latest` — resume the highest numbered plan, or the most
  recently modified legacy plan when no numbered plan exists.
- `/dwp-resume {plan_name} trust` (or `auto`, or "run to the end") — resume
  unattended: no questions between tasks (`../execute/SKILL.md` *Autonomous mode*).
- No parameter → interactive selection (Step 1).

Resolve the full name, ID, unique slug, or `latest` with `../shared/plan_paths.py
--plans-dir <dwp_dir>/plans resolve <selector>`. Validate its folder and
`README.md`; if absent, show available plans. A
folder without `README.md`, or whose README says `Plan Status: materializing`,
is a partial materialization (its `manifest.json` records the intended shape) —
point to `refine`; never execute it.

## Lite and promotion recovery

For v2 Lite plans, read the README's canonical task index, inline anchor record,
state locator and checkpoint before reading older history. A README checkbox wins
over state on desync. Do not treat missing task files as partial when the format
is Lite. Conversely, a `promotion` marker or `materialization: promoting` is a
hard recovery boundary: inspect its phase, preserve existing files and route to
`/dwp-refine promote` to complete the missing transaction step. Never execute
product work in a mixed representation.

An explicit execute/resume request can approve a ready plan's current scope
(Lite or Full). If a new requirement changes scope, criteria or gate, record
the checkpoint and use refine; do not promote or alter approvals implicitly.

## Trust boundary (write scope)

`allowed-tools` includes write-capable `Edit`, `Write`, and `Bash`.

**Writes:** identical scope to `execute` (task outputs, `.dwp/` working state,
per-task commits after gates pass) — resuming does not widen the boundary.

**It MUST NOT:** re-run or "fix up" a completed `[x]` task — under the **DWP
Resume Protocol** (`../spec/DWP_SPECIFICATION.md` §5.3) those are trusted as
recorded, and only three things reopen one: the developer asks, `refine` left a
`(re-validate: …)` marker, or the smoke test fails in a way that implicates it;
skip that post-interruption smoke test, which validates the **world** (the
cheapest standing check) before anything is built on it; repeat a commit, gate,
skill authoring, report or other external action the evidence shows already
happened; migrate a legacy plan (that is the refine migration surface —
`../shared/migrate_v6.py` on explicit request, preview first); push
without instruction; or write outside the repo checkout and
`.dwp/`.

## Workflow

### Step 0 — Check for Parameters
If a parameter was given, resolve the plan (or `latest`), validate folder +
README under `.dwp/plans/`, note `trust`/`auto`, and skip to Step 2. Otherwise
go to Step 1.

### Step 1 — Identify Plan
List plans with `../shared/plan_paths.py --plans-dir <dwp_dir>/plans list`.
Present an ID / name / `latest` menu; validate with `resolve`.

### Step 2 — Assess Current State (CRITICAL)

**Step 2.0a — Pending handoff packet (every generation).** A pending
**handoff packet** comes first: `python3 ../shared/swarm.py handoff show
--plan <dir> --pending` (exit 1: none), then `handoff accept --pane <pane>`; a refused
accept is a §7.3 boundary. The packet is data — the plan decides the next
action.

**Step 2.0 — Detect plan generation (v6).** A manifest contract pointer,
`contract.json` or a `contracts/` chain means **v6**: read `v6.md` and run
its recovery ladder (the journal is the truth) instead of the reconcile
below. A v5 folder continues as written — never migrate it here.

This step implements the **DWP Resume Protocol**
(`../spec/DWP_SPECIFICATION.md` §5.3) — the named ritual any resuming session
performs. It reads the **compact index first** and retrieves history **by
pointer**, never by replaying everything.

1. **Load the compact working index.** Read the plan README's task list (the
   small `[x]`/`[ ]` index, the `Plan Status` count, the `**Standard:**` line and
   the pre-approval note), the **Active context** block of `PROGRESS.md` (goal
   and invariants, active task and next action, unresolved blockers, current
   contracts and decisions in force, direct pointers to durable records), and —
   when present — `state.json`'s `status`, `checkpoint`, `blocked`, and the
   entries of the **active task and its named dependencies only** (not every
   gate of every task). Do **not** read every task file or the whole history by
   default; retrieve older records later, by pointer, when a step needs them.
2. **Gather actual evidence.** Run `git status`, `git log --oneline -10`, and
   `git diff` (if uncommitted changes exist). In a workspace without git, read
   `state.json`'s `checkpoint` instead (`../spec/PLAN_STATE.md` §4.4). Note the
   current revision.
3. **Reconcile Markdown, JSON and the workspace — before any work.** The
   markdown wins every disagreement (`../spec/PLAN_STATE.md` §5):
   - Where `state.json` exists, gather machine evidence first: run
     `python3 ../verify/plan_contract.py <plan-dir>` (read-only) and surface
     every finding — failed gates, `invalidated by refine` reliance, evidence
     admitting non-execution, dangling `log=` pointers — in `PROGRESS.md`.
     Markdown wins a **status** disagreement; it never lets a summary override
     a failed gate, admitted non-execution, invalidated evidence or an
     implementation the tree does not show.
   - `state.json` vs README checkboxes disagree → regenerate `state.json` from the
     README (and git log), note the reconciliation in `PROGRESS.md`, continue.
   - `state.json.blocked` is set → surface it: that is why the plan stopped.
   - A `[x]` task with no matching commit where the plan commits, a checkpoint
     that names work the tree does not show, a summary that contradicts the
     files, or instructions in the working index that contradict the task file
     → **do not trust the summary or the flag alone**: inspect the files and the
     log, record the finding in `PROGRESS.md`, and treat the task as the
     evidence says (in doubt, as not completed). Never repeat a committed action.
   - A README `[ ]` marked `(re-validate: …)` → its implementation exists; only
     its gates are rerun (`../refine/SKILL.md` 3.7).
   - The plan declares a standard newer than this skill → report and stop.
4. **Find the resumption point** — the **first unchecked `[ ]` task** (a task
   `in_progress` in `state.json` with a checkpoint is the active one).
5. **Classify partial work at its interruption boundary.** Using the evidence
   from steps 2–3 and the active task's Completion & Log, decide **which single
   step is missing** and do only that (`../spec/PLAN_STATE.md` §5.1):

   | Interrupted… | Evidence to check | Then |
   |---|---|---|
   | at a clean task boundary (the commonest case) | the last task's whole closure order present and consistent, checkpoint pointing at un-started work | **no repair step is owed** — take over (2.6), smoke-test (2.7), start the next task. Do not hunt for a missing step |
   | before the gate ran | uncommitted changes; no gate record | finish the implementation if incomplete; run the gate **once** |
   | after the gate, before the commit | gate record present, `passes: true`, and the recorded `fp=` still matches the world — same revision (`git rev-parse HEAD`), same dirty/generated files (`git status --porcelain`), same environment; any difference invalidates reuse | rerun the gate, record the fresh result, then commit **once** |
   | after the commit, before the README/log update | commit exists in `git log`; README still `[ ]` | complete log → README → PROGRESS → `state.json`; do **not** re-commit |
   | between Markdown and `state.json` updates | README `[x]`, state stale | regenerate `state.json`; nothing else |
   | after an external action (report, push, PR, message) | the action's own evidence (report id, remote branch, PR URL in the log) | do **not** repeat it; record that it already happened — a missing receipt is investigated against the service's actual state, never guessed or re-sent |
   | mid-implementation with no checkpoint note | dirty tree only | review the diff against the task; incorporate valid partial progress, finish the rest |

   Changed inputs since a recorded gate (a later edit, a `refine`, a new
   revision) invalidate that gate → rerun it. Where the table resumes the
   tail of the update order, the `state.json` step may use the shipped
   updater (`../shared/update-state.py`) as a targeted, atomic mutation;
   only the reconcile-from-markdown row regenerates the whole file. Retain
   the original review baseline: when the interruption landed mid-review, the
   diff and criteria under review at the halt are the baseline resumed —
   rebuild nothing the checkpoint already records. An interrupted completion
   publication leaves a `.finalizing.json` marker in the plan folder: inspect
   it and recover via `python3 ../shared/finalize_plan.py <plan-dir>
   --candidate <candidate.json> --recover` before any other plan action.
6. **Takeover from another agent or model.** If the checkpoint, log or
   `PROGRESS.md` was written by a different agent/model (`state.json.updated_by`,
   the log's wording) or the session is a fresh context: read the checkpoint
   **pointer** (`task`, `step`, `note`) and verify it against the files it names;
   detect contradictory instructions, stale state (revision changed), dirty work
   and missing evidence **before** continuing; record a one-line "takeover"
   entry in `PROGRESS.md` (who/what, revision, what was verified). Only then
   continue. The handoff artifact is the plan itself — nothing required may live
   only in a prior conversation, a proprietary task API, or a hook.
7. **Smoke-test before building:** run the repo's cheapest standing check (from
   `AGENTS.md` Quick Commands) to confirm the world still works before adding to
   it. A failing smoke test is investigated first.

### Step 3 — Report Resumption Status
Report, compactly: the plan's standard and pre-approval; completed `[x]` /
pending `[ ]` counts; the task to resume from and its interruption boundary
(Step 2.5) with the single next action; git state (uncommitted changes, recent
commits, last commit); reconciliation or takeover findings; any blocker. Location:
`.dwp/plans/<plan>/`.

### Step 4 — Handle Partial Work
Apply the Step 2.5 decision. Interactive: if the partial work is unclear or
unrelated, ask the user before proceeding. **Unattended:** unclear or unrelated
changes are a `../spec/AGENT_PROTOCOL.md` §7.3 boundary (reality diverged) —
record `state.json.blocked` with what was found and halt; do not guess and do
not discard work.

### Step 5 — Resume Execution
1. **NEVER redo `[x]` tasks** — trust the README, cross-check git commits (and
   the `(re-validate…)` exception above).
2. **NEVER skip `[ ]` tasks** — strict order; complete each fully.
3. **Continue from the first `[ ]` task** — open its file, read fully, address any
   logged blocker first.
4. **Complete the current task** under the standard **Execute** rules
   (`../execute/SKILL.md` Step 5): gate selected from the actual surface; repair
   in scope or stop; task-local closure (skills decision → log → README →
   PROGRESS → commit → `state.json`).
5. **Keep the working context bounded while executing.** On a stable run retain
   the already-loaded, unchanged context; re-read after a revision change, a
   handoff, a context compaction, or uncertainty. Retrieve older records
   **only** when a task's `Read Before Starting` names them, a decision cannot
   be found in the active-context block, or a pointer is stale or missing — and
   then verify what was retrieved rather than guess. Never drop an unresolved
   constraint or an active contract to save space.
6. **Continue** to the next `[ ]` task until done or paused — without asking
   whether to continue inside the plan's authorization.

> From here the standard **Execute** rules apply (`../execute/SKILL.md`),
> each on demand: Dailybot reports, the Final Review (a)–(e) with the one-time
> Executive Report offer, orchestrator task types and team-agents groups. A
> **legacy** plan (three final tasks) resumes under its own shape — resume never
> migrates it.

### Step 6 — Handle Blockers
If a task log or `state.json.blocked` shows a blocker, read it, fix the issue
within the task's authorized scope, re-run only the affected validations; on
pass: clear `blocked`, mark `[x]`, commit, continue; on fail: log again, stop,
request help (unattended: halt with `blocked` updated).

### Step 7 — Progress Reporting
After resuming and completing a task, show the compact result of
`../execute/SKILL.md` Step 6 (`✓ Resumed and completed: Task N` …). On blocker:
`✗ Task N blocked` with the blocker, action taken, status, and next step.

## The handoff artifact (what every session leaves behind)

Before yielding — at the end of a task, at a checkpoint before a planned
interruption, or when halting — the executing session **writes** (never only
says): the task's Completion & Log (or its partial notes), the README
checkboxes, the `PROGRESS.md` **Active context** block with the exact next
action and the evidence pointers, and `state.json` (`checkpoint` `{task, step,
at, note}` or `blocked`). That is the whole handoff: a fresh agent, another
model, or another harness resumes from these files with Step 2.

## Persistence: same workspace, new machine, or nothing to resume

- **Same workspace:** the handoff artifacts above are already on disk; Step 2
  is the whole recovery.
- **v6 plans:** the handoff artifact is the ledger export bundle — see
  `v6.md` *Cross-agent and cold resume* (a missing `state.json` on the
  receiving host is expected, not an incident).
- **New machine / fresh clone:** `.dwp/` is gitignored by design, so a fresh
  `git clone` carries **no** plan data — report that honestly, never
  fabricate progress from commits. Transfer is explicit and manual
  (`../shared/dwp-paths.md`, "Workspace persistence and transfer"): copy the
  **whole plan folder** — README, task files, `PROGRESS.md`, `manifest.json`,
  `state.json`, and `analysis_results/` with every cited gate log — check out
  the recorded repository revision, and re-create the dirty work the
  checkpoint names. The minimum handoff manifest: the complete plan folder,
  evidence pointers, repository revision(s), and required dirty work.
- **Missing artifacts** (no plan folder, absent state, dangling `log=` pointer):
  report what is missing and stop at that boundary; never reconstruct history
  from memory. No daemon, auto-upload, or automatic unignoring of `.dwp/`
  exists — persistence is a deliberate copy.

## Important Notes
- **Legacy plans:** execute as recorded; no automatic lifecycle migration.

## Error Handling
- Invalid plan structure → report; ask to fix (`refine`) or proceed with caution.
- Missing task file → report; ask whether to skip or create (unattended: blocker).
- Unclear git state → report findings; ask before proceeding (unattended: §7.3
  boundary).
- Contradictory checkpoint / summary vs files → trust the files; record; continue
  from the evidence.
- Unresolvable blocker → log in Completion & Log; report; wait for guidance.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall