deepworkplan-refine · diff
v7.7.0 to v7.7.1
1 added, 1 removed. Audit A to A.
---
name: deepworkplan-refine
description: Refine a Deep Work Plan — safely edit scope, add, split or reorder tasks, promote a Lite plan to Full task files, recover a partial promotion, or explicitly migrate a legacy plan, always preserving completed evidence.
- version: "7.7.0"
+ version: "7.7.1"
documentation_url: https://deepworkplan.com
user-invocable: true
allowed-tools: Bash, Read, Grep, Glob, Edit, Write
---
# DeepWorkPlan — Refine
Modify an **existing plan** (add / edit /
split / reorder tasks, update the README, promote a Lite plan to Full, or — only
on explicit request — migrate a legacy ending or a v5 plan to v6).
> **No drafts (2.4.0):** `create` materializes an executable Lite plan directly,
> so there is nothing to "refine into a plan" any more. `refine` operates on a
> plan folder under `.dwp/plans/`. The `.dwp/drafts/` directory and the
> `PLAN_{name}_draft_refined.md` artifact were removed in 2.4.0.
## Shared resources (read these)
- [`../shared/dwp-paths.md`](../shared/dwp-paths.md) — plans at `.dwp/plans/`,
plans at `.dwp/plans/<plan>/`.
- [`../shared/context.sh`](../shared/context.sh) — resolve `dwp_dir`.
- **Guide (essential — read for this flow):** [`../guide/authoring.md`](../guide/authoring.md) (plan README §4, task-file anatomy §5 incl. the Touched Surface, mandatory elements) and [`../guide/structure.md`](../guide/structure.md) (§1–§2 naming and folders).
- **Guide (conditional — read only when the trigger fires):** [`../guide/orchestrator.md`](../guide/orchestrator.md) / [`../guide/team-agents.md`](../guide/team-agents.md) only for plans that use them; [`../guide/execution.md`](../guide/execution.md) §6.1 when editing the Final Review (or a legacy plan's final tasks). Do not read other guide files for this flow; [`../guide/GUIDE.md`](../guide/GUIDE.md) is the routing index, consulted only when a section is not named above.
- **Shared contract (conditional — read the named steps only when the trigger fires):** [`../create/SKILL.md`](../create/SKILL.md) Steps 3.5–3.7 and 4.4–4.5 when promoting a Lite plan, adding or splitting a task, completing a partial materialization, or migrating — the **one** contract for task anatomy, gate selection, the Final Review, the ledger, the write order and the plan-quality check (refine never has a second template); [`../spec/PLAN_STATE.md`](../spec/PLAN_STATE.md) §5–§6 when the plan carries `state.json` (regeneration, evidence invalidation) or on `migrate` (the declared-migration line).
- **Conditional — read only when the trigger fires:** [`../examples/CREATE_PLAN.md`](../examples/CREATE_PLAN.md) — prompt patterns for professional rewriting; read it when rewriting plan-level structure or authoring new plan sections — task-level edits and promotions need only the contracts named above.
## Parameter Support
| Parameter | Description | Example |
|-----------|-------------|---------|
| (none) | Interactive — choose a plan | `/dwp-refine` |
| `plan {plan_name}` | Modify an existing final plan | `/dwp-refine plan auth_refactor` |
| `plan latest` | Modify the most recent plan | `/dwp-refine plan latest` |
| `migrate {plan_name}` | **Explicit** migration: a legacy three-task ending to the v5 Final Review shape, or a v5 plan to v6; never automatic | `/dwp-refine migrate auth_refactor` |
| `promote {plan_name}` | Promote a ready Lite plan to Full task files without changing scope | `/dwp-refine promote small_fix` |
## Trust boundary (write scope)
`allowed-tools` includes write-capable `Edit`, `Write`, and `Bash`.
**Writes:** edits confined to the target plan's files under
`.dwp/plans/<plan>/` — task content, ordering, the README's task list and
counts, `PROGRESS.md`, and the **regenerated** `state.json` — kept mutually
consistent. Deleting a completed task, dropping the Final Review (or a legacy
plan's final tasks), or invalidating completed evidence requires explicit
developer confirmation. `manifest.json` is **never** rewritten
(`../spec/PLAN_STATE.md` §2).
**It MUST NOT:** touch source files, write outside `.dwp/`, weaken a task's
acceptance criteria or validation gate without saying so in the diff summary,
change a plan's standard without an explicit `migrate` request, or commit/push
anything (refinement output stays uncommitted working state).
## Workflow
> Step 2 was the draft workflow; it was removed in 2.4.0. The remaining step
> numbers are unchanged so existing cross-references keep resolving.
### Step 0 — Determine Target Type
- No parameters → Step 1 (interactive).
- `plan {name}` / `plan latest` → Step 3 (Plan Workflow).
- `migrate {name}` → Step 4 (Explicit Migration).
- `promote {name}` → Step 5 (Lite Promotion).
### Step 1 — Interactive Selection
List the plans under `.dwp/plans/` and ask which one to modify (add / edit /
split / reorder tasks, adjust context, promote a Lite plan). Route to Step 3, or
to Step 5 when the developer asks to promote. Mention `migrate` only if the
selected plan is legacy.
## Plan Workflow
### Step 3 — Select and Modify a Final Plan
**3.1 Select.** If not specified, list plans with `../shared/plan_paths.py
--plans-dir <dwp_dir>/plans list`. Resolve a full name, numeric ID, unique slug,
or `latest` with the same helper's `resolve` command. `latest` is the highest
numbered plan when one exists, or the most recently modified legacy plan.
**3.2 Read and classify.** Read the plan README, the task files, `PROGRESS.md`,
and — when present — `manifest.json` and `state.json`. Establish:
- **The plan's generation.** A folder carrying `manifest.json` with a
contract pointer, `contract.json`, or a `contracts/` chain is a **v6
plan**: scope, acceptance, permissions or envelope changes are
**contract amendments** — author the revised contract (a copy of the
live one, edited), then run `python3 ../shared/ledger.py --plan <dir>
amend --contract <draft> --authority <who> --note <reason>
--human-note <file>` ([`../spec/V6_LIFECYCLE.md`](../spec/V6_LIFECYCLE.md)
§5: revision under `contracts/`, amendment event, fresh approval citing
the new contract id, re-evidence of the revised criteria — one
resumable verb, never by hand). The markdown task edits
below still apply to the plan's human layer; the contract never moves
through them. A v5 plan is never migrated to v6 *implicitly*; the one
explicit path is the migration surface below (3.2a).
- **3.2a — v5 → v6 migration (explicit request only).** When the developer
asks to migrate a v5 plan to v6, route to
[`../shared/migrate_v6.py`](../shared/migrate_v6.py) — never rewrite
records by hand: `preview` (integrity check + task mapping + the
re-evidence list — criteria whose v5 evidence cannot carry become
**blocked by default** until their gates re-run under v6), then
`migrate --authority WHO` (backup → contract synthesis → manifest swap →
journal import → projection; resumable at every phase), and `rollback`
for the explicit reverse (restores the v5 bytes from the verified
backup; refuses when post-migration v6 work exists unless `--force`).
Imported gate evidence is labeled `imported` with the v5 source digest —
never `observed`. The normative flow is
[`../spec/V6_LIFECYCLE.md`](../spec/V6_LIFECYCLE.md) §8. The reverse
direction (v6 → v5) does not exist.
- **The plan's standard** (`../spec/PLAN_STATE.md` §6.1): a declared
`**Standard:**` line in the README wins; otherwise `manifest.spec_version`;
otherwise (no manifest) the shape of its files. **New shape** = a single
`{N}.task_final_review.md` last. **Legacy shape** = three final tasks
(`security_review` → `skills_agents_discovery` → `executive_report`). Refine
**retains the plan's shape**; only Step 4 changes it.
- **Partial materialization**: a folder whose `README.md` is missing, says
`Plan Status: materializing`, or links a task file that does not exist is an
interrupted `create`. Read `manifest.json` and the README task list to report
the intended shape against what exists; offer to **complete** it (regenerate
only the missing files from `analysis_results/PLAN_ANALYSIS.md` per
`../create/SKILL.md` Step 4.4, leaving existing task files and the manifest
intact, then flip the status line) or **discard** it (explicit confirmation).
Never overwrite unrelated artifacts.
- Objective, context, guidelines, tasks and their `[x]`/`[ ]` status, and any
in-progress checkpoint.
**3.3 Show current state** — objective, standard (new / legacy), the task list
with status, and the location `.dwp/plans/<plan>/`.
**3.4 Choose modification:** Add task(s) / Edit task / Split task / Reorganize /
Update README / View task details / Done.
**3.5 Execute modifications**
**Final-task protection (lifecycle-aware, applies throughout):**
- **New shape:** the **Final Review** must remain the **last** task. It **CANNOT
be deleted or reordered**, but it **CAN be edited** (e.g. to add plan-specific
review criteria). If the user tries to delete or move it, explain: "The Final
Review is the mandatory final task. It can be edited but not deleted or
reordered."
- **Legacy shape:** Security Review stays third-to-last, Skills & Agents
Discovery second-to-last, Executive Report last; same rule — editable, never
deleted or reordered — unless the user runs an explicit `migrate` (Step 4).
- Insert positions are therefore `1..N-1` for a new-shape plan and `1..N-3` for a
legacy plan; `before-final` always means "immediately before the first final
task of this plan's shape".
- **Add task(s):** ask for the insert position (a number in the range above,
`before-final`, or `after {k}`), gather task details, create the task file with
the full standard structure (`../create/SKILL.md` Step 4.4 item 2: ten sections
incl. Touched Surface, selected gates, the skills-decision checklist step, the
`Skills disposition:` / `Gate record:` log lines), renumber subsequent files,
and run **3.6 Synchronize**.
- **Edit task:** show current content; apply changes to title / instructions /
acceptance criteria / Touched Surface / validation / everything. Final tasks are
editable. Then run **3.7 Invalidate affected evidence** and **3.6 Synchronize**.
- **Split task (unfinished, oversized):** split task `k` into two or more tasks
`k, k+1, …` — one objective per child (`../spec/DWP_SPECIFICATION.md` §6.4) —
such that **every requirement, acceptance criterion, constraint and
reference of the original lands in exactly one child** — nothing is dropped or
summarized. Distribute the original's Touched Surface, Read Before Starting
pointers and Outputs to the child that owns them; a child that consumes another
child's output names it in Read Before Starting. Carry any already-recorded
evidence (a partial Completion & Log, a checkpoint, a passing gate) into the
child that owns that work, verbatim, and leave a one-line pointer in the other
children. A `[x]` task is never split without explicit confirmation (it is
completed work). Renumber and run **3.6 Synchronize**.
- **Reorganize:** move / merge / delete. Renumber files as needed and **always
keep the plan's final task(s) last**. Warn before deleting a completed `[x]`
task (explicit confirmation). Merging keeps every requirement of both tasks.
- **Update README:** objective / context / global guidelines / execution rules
(including an explicit Executive Report request, which the Final Review honors).
- **View task details:** display the full task file.
- **Done:** run **3.6 Synchronize** once more, report modifications (what was
added / edited / split / reordered, which evidence was invalidated and why),
and offer to execute/resume via the **Execute** (`../execute/SKILL.md`) or
**Resume** (`../resume/SKILL.md`) sub-skill.
**3.6 Synchronize (after every modification — the plan must never be left
inconsistent):**
- README: task list entries, links (`N.task_{title}.md`), the `Plan Status:
X/N` count, the Analysis Outputs table, and any Team Agents Configuration
tables (Parallel Task Groups / roles) that name task numbers.
- Task files: numbers in file names and titles; `Read Before Starting`
references to renumbered tasks; Team Agents Metadata (`Can Run With`,
`Blocks`); `Blocks`/`Depends` wording that names a task.
- `PROGRESS.md`: the active task / next action, and a dated entry describing
the refinement (what changed, what was invalidated).
- `state.json` (when present): **regenerate it from the markdown**
(`../spec/PLAN_STATE.md` §5) — one entry per task file, ids and files matching
the disk, `task_count` = current number of task files, `completed_count` =
README `[x]` count. Entries of completed tasks keep their `completed_at`,
`commit`, `gates` and `outcome` (re-keyed if renumbered). Write atomically.
`manifest.json` is **not** touched: its `task_count` is the count at creation;
the live count is `state.json.task_count`.
- Never leave a README `[x]` for a task file that no longer exists, or a task
file with no README entry.
**3.7 Invalidate affected evidence (when requirements change):** when an edit
changes a task's acceptance criteria, scope, Touched Surface or gate — or
changes an upstream task whose outputs a **completed** task consumed — list the
affected completed tasks and, with the user's explicit confirmation, mark them
for re-validation: README checkbox back to `[ ]` with a `(re-validate:
requirements changed by refine on YYYY-MM-DD)` note, `state.json` entry status
`pending` with its gate records **kept** and their `evidence` prefixed
`invalidated by refine YYYY-MM-DD:`, and an **appended** "Invalidated" note in
the task's Completion & Log. Completed logs, commits and outcome records are
**never deleted or rewritten** — the executor re-runs the gates and re-marks the
task (`../spec/PLAN_STATE.md` §5.1). Without confirmation, record the concern in
`PROGRESS.md` and change nothing.
**Amendment record (append to the affected task's Completion & Log, and mirror
the entry in `PROGRESS.md`):** every scope, criterion or deferral change leaves
one durable record with these fields — no field is optional padding, and an
amendment is never backdated:
```
### Amendment {n} — YYYY-MM-DD
Original criterion: <verbatim quote of the criterion as authored>
Observed: <investigation finding, blocker, failed gate or changed input>
Disposition: revised criterion | deferred requirement | unexecuted scenario | failed gate
Revised criterion: <verbatim new criterion — only for "revised criterion">
Reason: <why the original cannot or should not stand>
Authority: user (explicit acceptance) | developer (refine request) | evidence (machine-detected mismatch)
Affected tasks: <ids>
Evidence invalidated: <gate commands per task, prefixed by refine>
Evidence preserved: <gate commands whose inputs are unchanged>
```
**What an amendment may close and what it may not.** Name the state honestly
(the five evidence states, `../spec/PLAN_STATE.md` "Evidence truth and
amendments"): a **completed
investigation** is real work but is never the execution of the original
criterion; an **unexecuted scenario** is recorded as not performed and
contributes no passing evidence; a **deferred requirement** moves the criterion
to a named destination task and needs `Authority: user` or `developer`; a
**failed gate** stays failing until the same acceptance intent is re-run and
passes; only an **achieved product outcome** — the criterion as written,
verified by its gate — completes the task unchanged. Correcting a broken
command preserves the same acceptance intent; substituting an easier check is
not repair, it is a revised criterion and needs its own amendment.
**Bounded exceptions.** The user may explicitly accept a bounded exception to a
criterion; record `Authority: user` with the acceptance (quote or reference)
and the boundary of what it covers. Pre-approval and trust authorize unattended
execution — they are never blanket permission to abandon a core objective. A
mandatory criterion that cannot be met is recorded as a blocker
(`state.json` `blocked`), never as completed work; the guarded writer refuses
that closure and read-only verification reports it.
## Explicit Migration
### Step 4 — Migrate a Legacy Plan (only on `migrate {name}`)
Migration is the **only** way a plan changes standard, and it happens **only**
when the developer asks for it explicitly (`../spec/DWP_SPECIFICATION.md` §6.5,
`../spec/PLAN_STATE.md` §6.1). Never suggest it as a side effect of another edit.
**Route by recorded generation before Step 4.1.** For a v5 plan, use the v5 →
v6 migration path in Step 3.2a and `../spec/V6_LIFECYCLE.md` §8: run
`python3 ../shared/migrate_v6.py --plan <dir> preview`, inspect the re-evidence
list and blockers, then run `python3 ../shared/migrate_v6.py --plan <dir>
--authority <who> migrate` on the explicit request. Report the migrated
contract, journal, projection, and criteria requiring new evidence. Do not
apply Steps 4.1–4.6 below to a v5 plan. Those steps only migrate a pre-v5
three-task ending to the retained v5 Final Review shape. A v6 plan already
uses the current generation and has no migration step.
1. **Classify** (Step 3.2). If the plan already has the v5 Final Review shape, say
so and stop.
2. **Preserve completed work.** Any `[x]` task — including a legacy final task
that has already run — is left exactly as it is. Only **unstarted** tasks may
take the new shape.
3. **Reshape the ending.** If none of the three legacy final tasks has started,
replace them with a single `{N}.task_final_review.md` (content per
`../create/SKILL.md` Step 4.4 item 3, incl. the security pass, final-state
validation, skills reconciliation, documentation reconciliation, completion
and report offer). If the
Security Review already ran, keep it and replace only the two unstarted
closing tasks with the Final Review's remaining parts (b)–(e); the Final
Review security pass (a) still runs the required local review over the
accumulated change set. Record the decision in `PROGRESS.md`.
4. **Add the new-shape elements** to unstarted tasks and to the plan: a Touched
Surface (planned surface, risk class, selected gate — derived from
`docs/TESTING_GUIDE.md`, or the full-suite fallback where the repository
documents no scoped invocation) on every unstarted behavior-changing task; the
skills-decision checklist step and the `Skills disposition:` / `Gate record:`
log lines; `analysis_results/SKILLS_CANDIDATES.md`; the Analysis Outputs
table rows; the Final Review note in the README.
5. **Declare it.** Add to the README Plan Variables the line
`**Standard:** DWP spec 2.3.0 (migrated from A.B.C on YYYY-MM-DD — <reason>)`
and a dated entry in `PROGRESS.md`. Leave `manifest.json` untouched (creation
provenance).
6. **Synchronize** (Step 3.6) and report: what was reshaped, what was preserved,
what the executor will do differently from here.
### Step 5 — Lite Promotion
Promotion changes only task representation. Read `spec/LITE_PLANS.md`, the Lite
README decision record and v2 state first. An explicit promotion request approves
the current proposal's representation change; record `Approval: approved` before
starting. It does not authorize product execution or a scope change. Refuse an
active task, an unresolved product-work blocker, or an unknown format. A
scope/requirement change is refine, not promotion.
**Recovery comes before starting a new transaction.** If a promotion marker
already exists (including after the format switched to Full), resume that same
transaction from its recorded phase. Verify the existing destination files
against the source records and evidence; write only missing files, preserve user
edits, and never overwrite conflicting evidence. A conflict becomes an actionable
blocker. Do not reject the marker that execute/resume sent here to recover, and
do not create a second promotion transaction.
1. Record `promotion: lite → full` intent atomically in state and README.
2. Generate Full task files for unchanged logical task IDs, preserving criteria,
gates, logs, completion status and lineage. Promotion never splits tasks or
grants invented evidence. Split or add work separately through refine, with
the affected approval and evidence invalidated before promotion resumes.
3. Validate contiguous IDs, links, gates, final review and Markdown/state
correspondence before switching the README's authoritative task representation.
4. Rewrite the state projection atomically with `format: full`, then clear the
promotion marker last. Preserve manifest creation provenance and never rewrite
it to disguise a changed live task count.
If interrupted, retain the marker and identify the exact missing boundary;
complete only missing files and preserve user edits. Execute/resume must not run
a marked plan. Full-to-Lite downgrade is not automatic.
## Important Notes
- **Preserve completed work:** never alter `[x]` tasks unless explicitly asked;
invalidation (3.7) marks them for re-validation, it does not rewrite them.
- **Renumber carefully:** keep task file numbers, README references, dependency
pointers, team-agents metadata and `state.json` ids in sync (3.6).
- **Maintain consistency:** task files follow the standard structure
(`../guide/authoring.md` §5; the shared contract in `../create/SKILL.md`).
- **One shape per plan:** refine keeps the plan's standard; `migrate` is the only
exception and is explicit.
- **No mandatory report:** refine never adds an Executive Report task; it may
record an explicit report request in the README guidelines.
- **Git ignore:** everything under `.dwp/` is git-ignored.
- **No draft artifact:** `refine` always operates on a plan folder under
`.dwp/plans/`. Nothing is written to `.dwp/drafts/` — it no longer exists.
## Error Handling
- Plan not found → list available plans and let the user select.
- Partial materialization (no `README.md`, `Plan Status: materializing`, or a dangling task link) → offer complete / discard (3.2).
- Task number out of range → show the valid range for this plan's shape and re-ask.
- Deleting or splitting a completed `[x]` task → confirm explicitly first.
- Plan has work in progress (a checkpoint or an `in_progress` task) → warn about
impact; suggest finishing the current task first; never edit the in-progress
task's evidence.
- `migrate` on a plan already in the requested generation and shape → report and stop.