To spec
The scoping session reached shared understanding of
what this Epic covers; this turns that understanding into
. It asks
nothing: every answer it needs has already been given, and the how is
's, in its own session, writing into the file this one creates.
Read
references/spec-template.md
first. It fixes every section of the file.
Requires for anything durable the synthesis turns up. A scoping session in context has already loaded it; load it if not.
The only file in the tree you write is
, and you write two of its sections as placeholders.
1. Open the Epic
The Epic is the one the session in context just scoped, or the reference the user passed — a root's slug, or
, which is child
of child
of the root, resolved down the numbered directories under
.
A
Split Epic stops the run. Split and Specified are mutually exclusive, so the Spec belongs to one of its leaves: name the children and ask which one. An Epic that already holds a
is being re-specified — say what the existing Spec covers, and what state any Tasks are in, and get the overwrite agreed before touching it.
Done when you hold one Epic that carries an
, no child directories, and the user's call to specify it.
2. Synthesise, do not interview
The answers are already yours. The session settled them question by question,
wrote the durable ones down, and
returned the rest. Asking again spends the user's attention on things they have already decided, and it is the one thing this skill must not do. This step has no checkpoint at all.
Assemble the Spec's material from what the session produced: the intent and
in
, the terms and ADRs the session wrote, and the findings under
.
When the session is not in context — a fresh
— read the same material off disk: this Epic's
, every ancestor's
up the path,
, the ADRs touching this area, the earlier siblings' code, and this Epic's own
. A gap you can close by reading is not a question; one that genuinely never got answered goes back to the user.
Write in the glossary's vocabulary throughout. Where the synthesis
contradicts an ADR, hand it to
rather than quietly overriding it — whether the contradiction amends or supersedes is that skill's call, not yours.
Done when every section of the template has its material, and you can say for each one which part of the session it came from.
3. Write the Spec
Write
beside the Epic's
, following the template exactly,
reference included.
## Implementation Decisions
and
each get the single line
and nothing else. Those two are the
how, they are
's to write, and that literal line is what tells every later reader — the user,
,
— that this leaf has a Spec and no design yet.
Two rules govern the rest, and they are what keeps a Spec true weeks later:
- Name surfaces, never file locations. A surface is what other code or a person calls: an endpoint and its shape, a URL, a CLI flag, an exported API, a module or component name, a package. Those are what was agreed and they survive a refactor;
apps/api/src/shift/shift.controller.ts
- is long. Every aspect of the work, one story each, in the template's
As a … I want … so that …
Anything the session settled that reaches past this Epic belongs in
or
, not only in the Spec: the tree is disposable and the Spec goes with it. Invoke
on anything still unrecorded before you finish.
Done when
exists, every section other than the two placeholders carries content, and no line names a path.
4. Hand off
Report in one line — the path — then name
as the next step and stop. The Epic is now
Specified and undesigned, and nothing can be built from it until the how is settled.