Skills / Engineering

spec

Interviews you about a feature, inspects the repository, writes a specification and an implementation plan, then hands implementation to a fresh session.

Group

Engineering

Kind

Action

Writes

A spec and a plan file; backlog items on a yes

Asks before

The spec location, when none is documented; adding to the backlog

When it runs

When you want to define or plan a feature before anyone implements it, or when you invoke the spec workflow, optionally with a feature description as the argument. Say it in your own words, for example:

• plan a new feature with me
• write a spec
• spec this feature

What it does

1. Interviews you. One question at a time about behavior, UX, edge cases, constraints and trade-offs, starting from the feature description when you gave one. It does not ask what the repository already answers.
2. Inspects the code. It reads the relevant code before it locks any decision.
3. Writes the specification. To the repository's documented specification location as <YYYY-MM-DD-feature>-spec.md; if none is documented it proposes docs/specs/ and asks you to confirm. Never into the planning location, where a spec would be read as the active plan. It covers goals, non-goals, flows, technical design, decisions with their rejected alternatives, contracts, failure handling, acceptance criteria, tests and unresolved decisions.
4. Writes the implementation plan. To the documented plan location as <YYYY-MM-DD-feature>.md: the goal, the decisions and a Status: in progress | done line, then every step as a - [ ] checkbox with What, Where, How, Test, Done when, a complexity (S/M/L) and a deployable invariant, ending with ## Open questions and a Next action: line. plan-status and session-retro read this shape.
5. Offers the backlog. It offers to add the plan's steps to the project backlog in the audit-to-backlog item format with the FEAT- prefix (complexity becomes Size, the step's Done when stays, its test becomes a runnable Check or a Manual: one, Where is the step's Where, and the evidence is the spec path and section) with an implementation-session line for them, so implement-backlog can execute them. The plan then links each item ID instead of repeating the step, so the work is counted once.
6. Hands off. It stops and gives you the plan path for a fresh session to implement from.

Boundaries

Related

• implement-backlog executes the backlog items the plan became.
• plan-status counts the plan's steps and lists its open questions.
• audit-to-backlog defines the backlog item format.
• The daily loop: the plan lives in the repository.