| name | spec-cancel |
| description | Cancel or supersede a spec, recording the reason so the decision is preserved |
| argument-hint | <spec folder or slug> [superseded-by <NNN>] |
| agent | spec-architect |
Cancel a Spec
Retire a spec that will not ship - the owner dropped it, scope changed, or another spec replaces it - without losing why. A cancelled spec is a recorded decision, not a deleted file.
Steps
- Resolve the spec. Read it enough to state what it was for.
- Determine reason and mode:
cancelled (will not be done) or superseded by NNN (another spec replaces it). The reason is required.
- If an open branch / PR exists for the spec, note it - the owner decides whether to close the PR; this skill does not delete pushed work.
- Set
status: cancelled (or status: superseded by NNN, with both linked) plus a one-line reason and the date in the spec's front page.
- Reconcile any draft docs the spec left behind (via
spec-document): a stubbed feature doc or an inferred rule that describes behavior which never shipped is removed or clearly marked not-shipped - never leave orphan docs implying a change that did not land.
- Archive per project convention - default: keep the folder with the cancelled status. Never silently delete; the record of "we decided not to" is itself valuable.
- Report: spec retired, reason, supersede link, docs reconciled, any open PR left for the owner.
Verify
status reads cancelled or superseded; the reason is recorded; a supersede chain links both ways; no pushed work was deleted.
Scope / hand-off
- Replacing it with a new plan -
spec-create (the superseder); link it. A reversible decision worth a durable record beyond the spec - spec-decision.
CRITICAL
- A reason is mandatory; never cancel silently.
- Never delete the spec file or pushed work to "cancel" - record the status; the decision must survive.