| name | spec-interview |
| description | Conduct an in-depth interview using the AskUserQuestion tool to elicit a complete specification, then write it to a file. Use whenever the user wants to create a detailed spec, PRD, requirements doc, design brief, or project plan through guided questioning — even when they don't explicitly say "interview" or "spec". Trigger on phrases like "spec out", "help me plan", "let's flesh out", "draft requirements for", "interview me about", "I want to think through", or anytime the user asks for a thorough back-and-forth before writing something down. |
Spec Interview
Turn a vague idea into a detailed written specification by interviewing the user with the AskUserQuestion tool. The interview keeps going — non-obvious questions, real tradeoffs — until the user says stop. Then write the spec to a file they can refer back to.
Why this works
People rarely have the full spec in their head when they start, and typing every detail into open-ended chat is slow and exhausting. The AskUserQuestion tool changes the dynamic: it presents 2–4 concrete options per question, which surfaces tradeoffs the user hadn't considered and is much faster than free-text. Your job is to feed that strength — ask the questions a thoughtful collaborator would ask after sitting with the problem for ten minutes, not the surface-level ones.
How to run the interview
Use AskUserQuestion exclusively for elicitation. Don't ask questions in plain prose — that loses the structured-choice advantage and slows the user down. Each call can hold 1–4 questions; group related questions into the same call when the user can reasonably consider them together.
Cover the dimensions a real spec needs:
- The problem and who has it (which user, in which moment, what they do today instead)
- Scope boundaries — especially what's out of scope (often more revealing than what's in)
- Technical implementation choices and their tradeoffs (stack, data model, hosting, integrations, auth)
- UX and interaction details (key screens, edge-case flows, empty/error/loading states)
- Concerns and risks (failure modes, scaling cliffs, compliance, abuse, second-order effects)
- Success criteria (how the user will know it worked, in measurable terms)
- Constraints (budget, timeline, team size, existing systems that must be respected)
Make the questions non-obvious
Skip questions where the answer is obvious or doesn't change anything downstream. Aim for questions where each option teaches the user something about their own preferences — concrete forks in the road, not abstract preferences. Some shapes that work:
- Force a real fork. "When two users edit the same row at once: last-write-wins, optimistic locking with a merge prompt, or row-level locking that blocks the second writer?"
- Surface implicit assumptions. "Who pays the third-party API costs — your service, the buyer, or the seller?"
- Make them choose between things they'd both like. "Faster page loads via aggressive caching, or fresher data with no cache — pick the one you'd defend in a meeting."
- Probe failure modes. "If the payments provider is down for an hour, do you queue the orders, fail loudly, or fall back to a secondary provider?"
Avoid asking things you can reasonably infer from earlier answers — that wastes the user's attention. After each round, internalize what you learned and let it shape the next round. If an answer opens a new dimension (regulated data, an unexpected user type, a new integration), follow it.
When to stop
Keep interviewing until the user explicitly says they're done, want to wrap up, or asks for the spec to be written. Don't self-terminate early because the basics feel covered — the value of this skill is going deeper than the user would on their own. If you're running out of new ground, push into areas that usually get skipped: rollback plans, what happens at 10x scale, what gets cut if the timeline halves, who owns the system in six months, what migrations would be painful later.
Writing the spec
Once the user signals stop, write the spec to a file with the Write tool. Use this structure as a starting point and adapt to the project's nature:
# [Project name]
## Overview
One paragraph: what this is, who it's for, why it matters.
## Goals
What success looks like, in concrete terms.
## Non-goals
What's explicitly out of scope and why.
## User stories / scenarios
Specific people doing specific things, including the messy edge cases.
## Functional requirements
What it does, behavior by behavior.
## Technical design
Stack, data model, key services, integrations, deployment.
## UX & interaction design
Key flows, screens, states. Reference decisions made during the interview.
## Risks & open questions
Things that could go wrong, decisions deferred, assumptions to validate.
## Constraints
Timeline, budget, team, existing systems.
## Success metrics
How you'll know it worked.
Pull directly from the interview answers — don't invent details to fill space. If a section is genuinely empty because the interview didn't reach it, write (not yet specified — open question) rather than hallucinating content. That honesty is more useful to the user than a polished-looking but fabricated section.
Output location
Write the spec to the user's selected workspace folder if one is connected — that way the file persists on their computer after the session ends. If no folder is connected, write it to the session outputs folder so it can still be linked back to the user.
Use a filename that reflects the project, kebab-case, .md extension: <project-name>-spec.md (for example, referral-program-spec.md). If the project's name is unclear, ask the user before writing rather than guessing.
After writing, share the file with a computer:// link and a one-line summary of what it covers. Don't recap the whole interview — the user just lived through it. They want to read the file, not a meta-narrative about it.
