skill-spec-drafting

Follow the eleven-step process: establish the problem and goal, inspect current state, define scope and non-goals, then specify required outcomes, behavioral contracts, design decisions, invariants, migration risk, and observable acceptance criteria. Save the result using the detailed specification template under the specs directory.

Draft a specification when behavior, interfaces, data contracts, state transitions, or migrations must be defined before implementation, or when work is cross-cutting or expensive to reverse. Skip it when the change is local, reversible, design-clear, and safely executable without a specification.

A draft specification (status: proposed) is used while behavior or design still needs prototype validation. After explicit approval and completion of post-approval inputs, the same file is promoted in place to a detailed specification (status: active) using the detailed template.

No. The specification owns problem, behavior, contracts, design decisions, and acceptance intent. Exact files, task order, commands, dependencies, and rollout steps belong to the implementation plan, which is produced later by the plan-writing skill.

Unresolved questions that change required behavior or design block activation. Non-blocking deferrals need durable approval evidence with an owner or trigger, and required post-approval inputs such as Design Export evidence must be complete before promotion.