interview-user

What this skill does

# interview-user

Elicit structure from an under-formed idea by asking one question at a time, recording each question and answer in a persistent tree on disk. The tree is the source of truth — not chat history.

This skill produces raw material. It does not produce the final artifact. When the user signals "we're done," hand off; do not slide into drafting the PRD/design doc/memo inline.

## When to use

Trigger on phrases like: "interview me about X," "grill this idea," "help me think through Y," "let's poke holes in this plan," "I want to design X but haven't thought it through."

Do not use for: well-scoped implementation tasks, debugging, code review, or any case where the user already knows what they want and is asking for execution.

## Core discipline

**Write the question down before asking it.** This is the single most important rule. The on-disk tree is updated *first*, then the question is posed to the user. Skipping this step collapses the skill into ordinary chat and forfeits the resumability and branch-coverage value.

**One question at a time.** Always. Multi-question messages overwhelm the user and produce shallow answers.

**Preserve the user's coinages verbatim.** When the user invents a term or lands a load-bearing phrasing -- "constraint-driven development," "one person's fix becomes everybody's fix" -- record those exact words in the **Answer**. Paraphrase only the connective tissue around them. The user's own vocabulary is the highest-value material the interview captures; a paraphrase of a coinage discards the thing worth keeping. This matters most for dictated input, which runs long and self-correcting with the gold buried in one specific clause -- read for the clause, keep it intact.

**Recommend an answer only on convergent questions.** A convergent question picks among known options, ratifies a default, or scopes something concrete; lead with a recommendation so the user can "yes / different / why?" A divergent question is generative -- values, success criteria, "what should X be" -- where a confident guess anchors the user before they've explored. Ask divergent questions raw. If the user stalls or asks "what do you think?", *then* offer a recommendation. See "Recommending answers" below.

**Read the repo to find gaps, not to answer questions for the user.** The interview's goal is to get the user to structure their thinking, not to close nodes efficiently. The repo tells you what *is*; the interview elicits what the user *intends*, *values*, or *believes is true*. Those are different artifacts.

Three cases:

- **Pure factual lookup** (what version, what endpoint, what schema) -- read it, record the answer with a `(file:line)` citation, do not ask the user.
- **Repo says X, user's view of X is the elicitation** -- read the repo so the question is *informed*, then ask the user anyway. Example: the code currently routes auth through middleware A; the question "should auth keep going through A?" still goes to the user, with the current state surfaced as context.
- **Intent / values / strategy** -- the repo cannot answer. Do not look. Ask raw.

The repo's primary job in this skill is gap-finding: where does the user's idea conflict with, duplicate, or ignore what already exists? Turn those gaps into questions for the user, not answers on the user's behalf.

**After each answer: decide, write, then resume.** Every user answer triggers the same three-step loop:

1. **Decide if follow-ups are necessary.** Pick from the taxonomy below. The default is *none* -- close the node and move on. A follow-up earns its place only if its answer could change the parent's answer or change the downstream artifact (MECE pruning rule: if the child cannot move the parent, do not ask it).
2. **Write follow-ups as children to the file before asking anything.** Same externalize-before-asking rule as the rest of the skill. Add each child with full tagging (`necessary`/`exploratory`, `convergent`/`divergent`) and a recommended answer on convergent children. Update **Open threads** and **Touched**.
3. **Resume the one-question-at-a-time loop.** Pose the first new child to the user. The other new children wait their turn alongside any pre-existing open nodes; pick the next question by leverage, not by tree position.

If step 1 produced no follow-ups, mark the parent `answered` and move to the next open node. No silent moves -- every answer either closes its parent or branches.

A substantive answer can also resolve *other* open nodes -- a reframe often dissolves seed questions posed earlier. When that happens, mark each of those nodes `subsumed` with a **Reason:** cross-referencing the resolving node, rather than leaving them open or quietly deleting them.

### Follow-up taxonomy

Pick one per answer (including "none"):

- **Close, no follow-up.** Default. The answer is complete enough.
- **Clarify.** The answer is ambiguous. Cite the interpretations: "I'm reading this two ways: X or Y. Which?"
- **Probe an unstated assumption.** Name the implicit premise and ask: "This assumes `<X>`. Is that right?"
- **Test against constraints.** The answer conflicts with declared scope, an earlier answer, or repo reality. Surface the conflict, ask the user to resolve.
- **Pull an implication.** "If `<answer>`, then what about `<consequence>`?" Use sparingly -- the easiest type to over-generate.
- **Adversarial probe.** "What would have to be true for this to be the wrong call?" Reserve for high-stakes nodes where the user seems too confident.

### Follow-up anti-patterns

- **Paraphrase-as-question** ("so you're saying X?") -- record the answer in your own words; do not make the user ratify your phrasing.
- **"Tell me more"** -- unstructured; signals the agent does not know what gap to probe. If you cannot name what you are trying to learn, close the node.
- **Symmetric follow-up across siblings** -- generating the same follow-up type on every node out of habit. Each follow-up is a fresh judgment.
- **Asking before writing.** Follow-ups go into the file first, then to the user. Same rule as root questions.

## Artifact

Question trees live in `docs/questions/<session-name>.md` relative to the current working directory, unless the user or standing instructions specify otherwise. One tree per session. Create the directory if it does not exist.

Before creating the directory, check whether the cwd looks like a build, content, or output location -- a Hugo/Jekyll page bundle, `content/`, `public/`, `dist/`, `build/`, `site/`, or similar -- where the tree would land inside publishable or generated files. If so, propose a repo-root location instead (e.g. the repository's top-level `docs/questions/`) and confirm before writing.

### Node format

Each node is a nested markdown bullet with this shape:

```markdown
- **Q1.2** [open, necessary, divergent] What's the success metric?
  - **Answer:** (filled in once answered) -- brief, plus any file refs consulted
  - **Touched:** 2026-05-17
  - **Q1.2.1** [open, exploratory, convergent] Does it segment by team?
    - **Recommend:** yes, segment by owning team
```

Field reference:

- **ID** -- stable, dotted (`Q1`, `Q1.2`, `Q1.2.3`). Never renumber; if a node is abandoned its ID stays as a tombstone.
- **Status** -- one of `open`, `answered`, `deferred`, `abandoned`, `subsumed`.
- **Necessity** -- `necessary` (must be answered to close the parent) or `exploratory` (interesting but optional).
- **Shape** -- `convergent` (pick among options, ratify a default, scope something concrete) or `divergent` (generative -- values, criteria, open "what should X be"). Drives whether to lead with a recommendation.
- **Recommend** -- the agent's proposed answer. Present *with* convergent questions; offer on divergent questions only if the user stalls.
- **Answer** -- the user's actual answer. Paraphrase the connective tissue for brevity, but keep coined terms and load-bearing phrasings verbatim (see "Preserve the user's coinages verbatim" abo