| name | execution-plans |
| description | Use when work is complex, long-running, multi-step, cross-boundary, likely to span multiple PRs/sessions, or needs handoff-ready planning under plans/. |
| metadata | {"short-description":"ExecPlan: plan/WBS/progress + handoff","requires":["references/execution-plans.md"],"resources":["references/model-routing.md","references/subagent-execution.md"],"templates":["templates/subagent-report.md","templates/subagent-task-brief.md","templates/supervisor-review-request.md"]} |
Purpose
Use this skill to create (or update) an ExecPlan: a living, self-contained plan that makes long work measurable, reviewable, and handoff-ready.
This addresses three recurring failure modes in agentic coding:
- work starts without a shared plan, so scope drifts
- progress is not tracked, so “where are we?” is unclear
- context handoff is weak, so long tasks regress or stall
When to use
This skill is mandatory when any ExecPlan trigger is true (see PLANS.md), including:
- multi-step / multi-session tasks
- cross-boundary refactors or new modules
- tasks with meaningful unknowns (API choices, rollout, concurrency, performance)
It is also a good default when you are unsure.
How to use
-
Open PLANS.md and references/execution-plans.md.
-
Create or update a plan file under plans/ using plans/_template_execplan.md.
- Quick start helper:
python scripts/init_artifact.py --kind execplan --slug <ticket-or-topic>
2.5) Run a Design→WBS coverage check: every module, file, or deliverable
named in the Design section must map to at least one WBS item, or be listed
as explicitly deferred with a reason. Re-run this check whenever the Design
section changes.
2.6) If the plan will use a subagent, worker, delegated model, or generated
custom agent, open references/subagent-execution.md before invoking it.
If model choice matters, also open references/model-routing.md. Create the
task brief first from templates/subagent-task-brief.md; require the worker
report format in templates/subagent-report.md; use
templates/supervisor-review-request.md when asking another agent to review
delegated output.
- Keep the plan up to date while you work:
- update Progress (WBS) as items complete
- record Surprises & discoveries as you learn new constraints
- record Decision log entries for trade-offs
- record summaries of
implementation-economy budgets and design-balance responsibility maps when those branches are triggered
- Target re-forecast: at every phase/milestone boundary, re-forecast each
quantitative target using current measurements. If the forecast misses a
declared target by more than ~20%, append a Decision log entry choosing one
of: re-scope (add work), re-baseline (change the target), or accept-miss
(with rationale). Do not defer this decision to the final measurement.
- Surprise escalation: when a Surprises entry invalidates an assumption
behind a quantitative target (e.g., "this file cannot be deleted"), the same
commit must update the target forecast.
- update Handoff whenever you pause or finish a milestone
- If a human is present and the change is risky/irreversible, ask for approval after drafting the plan and before large edits.
Gotchas
- Common pitfall: creating the plan first but not updating Progress (WBS).
Instead: update status for each completed task and keep todo/in-progress/done current.
- Common pitfall: handling major direction changes verbally and not recording a Decision log.
Instead: append reason, alternatives, and adoption decision to the plan Decision log.
- Common pitfall: leaving stale handoff notes at session end, forcing the next person to re-investigate.
Instead: always update Handoff with current status / next step / blocker / commands run before stopping.
- Common pitfall: moving ahead ad-hoc on complex work without creating an ExecPlan.
Instead: if any PLANS.md trigger applies, create plans/<slug>.md before starting.
- Common pitfall: the Design section names deliverables (modules, files)
that never receive a WBS item, so they are silently never built.
Instead: run the Design→WBS coverage check and mark uncovered
deliverables as deferred-with-reason in the plan.
Output expectation
When this skill is used, produce:
- An updated ExecPlan file in
plans/…
- A short status update in the standard format (see the reference)
- Clear “what’s next” items if work is not finished
