---
name: interview-to-specs
description: "Stage 1 of the feature workflow. Use when an intent, idea, or rough plan exists but no spec has been written to disk yet. Interviews the user one question at a time, challenges the idea against the repo's glossary and recorded decisions, and produces a feature spec under docs/specs/ plus glossary updates in CONTEXT.md and any warranted ADRs. Also use when a downstream skill reports that no spec exists, or when a review shows the spec or an ADR was wrong. Do not use when a spec already exists and the user wants an implementation plan, which is specs-to-plan."
metadata:
  version: 1.0.0
  stage: 1 of 4
  derived-from: grill-with-docs
  original-author: Matt Pocock
  upstream: https://github.com/mattpocock/skills
  upstream-path: skills/engineering/grill-with-docs
  license: MIT
---

# 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.

| Artifact | Where | What you take from it |
|---|---|---|
| Glossary | `CONTEXT.md`, or the files named by `CONTEXT-MAP.md` | the canonical term for every concept in play |
| Decisions | `docs/adr/` | what is already settled and must not be relitigated casually |
| Existing specs | `docs/specs/`, newest first | whether this intent is already covered |
| The code | wherever the intent touches | what is actually true today |

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](./CONTEXT-FORMAT.md).
- **A decision passes all three tests** below: write the ADR immediately.
  Format in [ADR-FORMAT.md](./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](./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.