interview-to-specs

Interview to Specs

Stage 1 of 4. Consumes the user's intent and the codebase. Produces a spec, glossary updates, and ADRs. Downstream, specs-to-plan reads what this skill writes.

Announce at start: "Using interview-to-specs to interview you about this and produce a spec."

1. Read before you ask

Read these first. Never ask a question the repo already answers.

Then state, in one short block, which of those existed and which did not. Do not create any of them yet.

If an existing spec already covers this intent, stop and print exactly:

A spec for this already exists:

  <path>   status: <status>

Tell me whether to revise that spec or start a separate one.
I will not do either until you answer.

2. Interview

The discipline is the whole value of this stage. Follow it exactly.

• One question at a time. Ask, then wait for the answer. Never stack two questions

in one message, and never move on before the user has answered.

• Always carry your recommendation. Every question states the answer you would

pick and why. A bare question makes the user do your thinking.

• Explore instead of asking. If the codebase can answer the question, go read it.

Report what you found and ask only about what the code cannot settle.

• Walk the tree. Resolve dependencies between decisions in order. Do not ask about

a leaf while its parent is open.

Four things to press on, from upstream:

• Challenge against the glossary. When a term conflicts with CONTEXT.md, say so

at once. "Your glossary defines cancellation as X, but you seem to mean Y. Which is it?"

• Sharpen fuzzy language. When a term is vague or overloaded, propose a precise

canonical one. "You said account. Do you mean the Customer or the User? Those differ."

• Use concrete scenarios. Invent specific cases that probe edges and force the user

to be precise about where one concept stops and the next begins.

• Cross reference with code. When the user states how something works, check whether

the code agrees. Surface every contradiction you find.

If a domain-modeling skill is installed, use it for the modelling portions. This skill works standalone without it.

3. Write as you go

Do not batch. The moment something resolves, write it.

• A term resolves to a canonical name and definition: update CONTEXT.md immediately.

Format in CONTEXT-FORMAT.md.

• A decision passes all three tests below: write the ADR immediately.

Format in ADR-FORMAT.md.

An ADR is warranted only when all three are true:

1. Hard to reverse. Changing your mind later costs something real.
2. Surprising without context. A future reader will ask why it was done this way.
3. The result of a real trade-off. Genuine alternatives existed and one was chosen.

If any of the three is missing, it is not an ADR. It belongs in the spec.

CONTEXT.md is a glossary and nothing else. No implementation detail, no requirements, no scratch notes. Content that is neither a term nor an ADR goes in the spec.

Create files lazily. If CONTEXT.md does not exist, create it when the first term resolves. If docs/adr/ does not exist, create it when the first ADR is warranted.

Before creating any file, run `git check-ignore -q <path>`. If the path is ignored, stop and print exactly:

<path> is covered by .gitignore.

This workflow keeps its artifacts in git. A gitignored plan means plan-to-code
cannot commit progress, and a gitignored spec means code-to-review cannot read it.

Fix .gitignore, or tell me a different path. I will not write until you answer.

4. Scope check

One spec produces exactly one plan. If the intent covers several independent subsystems, each of which is worth building and testing on its own, splitting is cheap now and expensive later.

When the intent is too large, stop and print exactly:

This intent looks like <N> independent pieces of work:

  1. <piece>
  2. <piece>

Each one is separately buildable and separately testable, so it should get its own
spec, its own plan, and its own review.

Say "split" and I will interview each in turn, or "one spec" and I will write a
single one. I will not choose for you.

5. Draft the spec, then confirm

The spec is the only artifact written at the end rather than inline, because it is the synthesis of everything the interview settled.

Choose the feature slug once. Lowercase ASCII, kebab-case, no date, no trailing noun like "feature" or "plan". This slug is the join key of the entire workflow and every downstream artifact reuses it verbatim.

Draft the spec per SPEC-FORMAT.md. Show it in full, then print exactly:

That is the full spec. It will be written to:

  docs/specs/<YYYY-MM-DD>-<slug>.md   status: approved

Reply "write it" to save it as approved, "draft" to save it with status draft, or
tell me what to change. I will not write the file until you answer.

Write the file only after the user answers. write it saves status: approved. draft saves status: draft. Anything else is a revision, so revise and ask again.

6. Hand off

Print exactly this, filled in:

interview-to-specs complete.

Written:
  docs/specs/<YYYY-MM-DD>-<slug>.md      (new, status: <status>)
  CONTEXT.md                             (<n> terms added: <terms>)
  docs/adr/<NNNN>-<decision-slug>.md     (new)

Feature slug: <slug>

Next stage: specs-to-plan, in a fresh session.

  Use the specs-to-plan skill with docs/specs/<YYYY-MM-DD>-<slug>.md

This session is done.

Omit any line for an artifact this session did not write. Then stop.

Refuse rather than improvise

• No answer from the user means no question answered. Never fill one in yourself.
• A requirement the user did not state does not go in the spec.
• A decision that fails the three ADR tests does not become an ADR.
• An existing ADR that this intent contradicts is raised out loud, not planned around.

The remedy is a new ADR that supersedes it, decided in this interview.