---
name: interview
description: When working with a vague spec, a new feature idea, a half-written SPEC.md, or when the user says "interview me about X", "spec this out", "grill me on this", "ask me everything", "turn this into a proper spec" — run a rigorous AskUserQuestion loop that drags out implementation details, UX choices, tradeoffs, and unspoken concerns, then writes SPEC.md. Use this BEFORE any feature touching more than one file.
when_to_use: |
  User says: "interview me", "spec this", "ask me questions about", "help me think through", "what am I missing", "turn this into a spec", "flesh out this idea", "grill me", "deep dive the requirements".
  Also: any time a SPEC.md is being created, any time a feature crosses >1 file, any time the stated requirement leaves obvious unknowns.
argument-hint: "[optional path to existing spec/notes to extend]"
user-invocable: true
context: fork
agent: general-purpose
allowed-tools: Read, Write, Glob, Grep, AskUserQuestion
---

# Interview → SPEC.md

Extract a complete, actionable spec from the user's head by interrogation. You are not a scribe — you are an interviewer with an agenda: produce a SPEC.md another agent could implement without asking a single follow-up.

## Mission

Turn vague intent (`$ARGUMENTS` = path to prior notes/spec if any, otherwise an empty canvas) into a SPEC.md with zero ambiguity on:
1. **Problem** — what user-visible pain this solves, measured how
2. **Scope** — in-scope, out-of-scope, non-goals (explicit)
3. **Behavior** — input → output contract, error modes, edge cases
4. **UX** — every touch point, happy path + failure path
5. **Implementation constraints** — stack, files, existing patterns to follow, what not to touch
6. **Tradeoffs** — at least 2 rejected alternatives with reason rejected
7. **Risks** — what could go wrong, how you'd know
8. **Success criteria** — shippable when what is true

## Workflow

1. **Read prior context.** If `$ARGUMENTS` is a path, Read it. Glob for adjacent `SPEC.md`, `README.md`, `docs/**/*.md`. Never start cold if context exists.
2. **Plan your dimensions.** Before asking anything, write a private checklist of the 8 dimensions above. Mark which are already answered from context.
3. **Ask in batches.** Use AskUserQuestion with 2–4 questions per batch. Each question must have 3–5 concrete multi-choice options plus a free-text "other." No open-ended "what do you want?" — that wastes the user's time.
4. **Drive with hypotheticals.** Don't ask "what should happen on error?" Ask "if the API returns 429, do we (a) retry with backoff, (b) surface to user, (c) silently drop, (d) something else?" Force a choice.
5. **Probe contradictions.** If answer N contradicts answer M, surface it: "Earlier you said X; this implies Y. Which wins?"
6. **Stop when the spec would compile.** When you can write SPEC.md with no TBDs, stop. Don't interview for interview's sake.
7. **Write SPEC.md.** At repo root or `$ARGUMENTS` directory if provided. Structure below.

## SPEC.md Template

```markdown
# SPEC: <feature name>

**Status:** draft | approved
**Date:** YYYY-MM-DD
**Author:** <user>

## Problem
<user-visible pain, 1-3 sentences. Who feels it, how often, impact.>

## Success criteria
- [ ] <binary, testable statement>
- [ ] ...

## Scope
**In:** <bullet list>
**Out:** <bullet list of explicit non-goals>

## Behavior
### Happy path
<step-by-step>

### Error / edge cases
| Case | Behavior |
|------|----------|
| ... | ... |

## UX
<every surface: CLI flags, UI elements, log messages, exit codes>

## Implementation
**Stack:** <languages, frameworks, versions>
**Files to touch:** <best estimate>
**Patterns to follow:** <existing examples in repo>
**Do not touch:** <explicit exclusions>

## Alternatives considered
1. **<rejected approach>** — rejected because <reason>
2. ...

## Risks
- <risk> → <mitigation / detection>

## Open questions
<only if user explicitly deferred. Empty = ready to implement.>
```

## Gotchas

- **Don't let the user drift into implementation before scope is locked.** If they start writing code mid-interview, note it and steer back: "Hold that — first, is this in scope?"
- **Multi-choice > free text.** Free-text answers feel thorough but force re-interviews. Always offer concrete options.
- **"I don't know" is a real answer.** Capture it in Open questions, don't invent a spec.
- **Surface tradeoffs explicitly.** If the user picks option A, name what they gave up by not picking B. Users routinely pick the first thing without realizing the cost.
- **Don't rubber-stamp.** If the user's answer is vague ("make it fast"), demand a number. "Fast = <50ms p95? <200ms? budget?"
- **Stop interviewing once spec would compile.** Perfect is the enemy of done. If 8 dimensions are filled, write the file.
- **Don't ask about things you can verify yourself.** If the repo already uses Zod, don't ask "what validation library?" — read and state it.
- **Always ask about failure modes LAST.** Users start optimistic; error-case thinking needs momentum first.
- **When interviewing against an existing SPEC.md, diff-mode:** only ask about dimensions that are missing or contradictory. Don't re-litigate what's settled.

## References
T04, T20 findings: interview-style elicitation produces specs 3–5× more implementable than free-form ideation. AskUserQuestion with multi-choice outperforms open prompt by large margins.