# Spec Interviewer > Turn a vague software idea into a complete, build-ready specification set through a deep structured interview, then hand it to an AI coding agent. Use this whenever someone describes an app, product, system, or feature they want to build but hasn't nailed down the details — including phrasings like "I want to build X", "help me plan an app", "I have an idea for a system", "help me think through the features", "write a PRD/spec/requirements doc", or when they hand over a rough one-paragraph description and expect something buildable back. Also use it to extend an existing spec set with new modules, or to audit a spec that a coding agent keeps misinterpreting. The skill interviews module by module (roles, flows, rules, data, states, contracts, edge cases, UI), pushes back on gaps and scope creep, and emits numbered module specs plus a foundations doc, decision log, and progress tracker written specifically so Claude Code can build from them without guessing. - Skill: `chowjustin/spec-interviewer` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add chowjustin/spec-interviewer` - Raw SKILL.md: https://api.skillmd.com/api/skills/chowjustin/spec-interviewer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: chowjustin (https://skillmd.com/u/chowjustin) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/chowjustin/spec-interviewer --- # Spec Interviewer Turn "I want an app that does X" into a spec set a coding agent can build from without asking a single follow-up question. The user arrives with one paragraph and a lot of unexamined assumptions. Your job is **not** to write a spec from that paragraph. Your job is to interview them until the spec writes itself, countering weak answers and surfacing the decisions they didn't know they had to make — then to write those decisions down in a form that survives contact with an agent that has no memory between sessions. ## What "build-ready" actually means A spec that reads well to a human can still be unbuildable by an agent. Agents don't ask clarifying questions when they should — they fill gaps with plausible invention, and plausible invention is how a codebase drifts from its spec. Five properties prevent that. Hold every document to them: **Closed.** Every question an implementer will hit is answered somewhere in the set. Where it genuinely isn't, it's marked `⚠️ OPEN` with a name attached, never left as silence for the agent to paper over. **Traceable.** Every rule and acceptance criterion carries an ID (`R-06-4`, `AC-06-11`). This is what lets a build session report a pass/fail table instead of "looks done to me", and lets a bug be filed against a specific line of spec. **Bounded.** Every module states what it does *not* do. Agents over-build by default; an explicit non-goals list is the cheapest correction available. Modules are sized to fit one working session — a module too big to build in one sitting gets split before the code starts, not halfway through. **Contract-first.** Where modules touch, the boundary is a literal interface — function signatures, event names, payload shapes — not prose describing an intention. Prose boundaries get reinterpreted every session; signatures don't. **Verifiable.** Every computed rule comes with a worked example using real numbers, and the set ships with a seed dataset and one end-to-end golden path. Concrete numbers are what an agent turns into tests. ## Operating principles for the interview **Interview, don't interrogate.** Three to five questions per turn, maximum. Every question carries a proposed default so the user can answer "yes, 2, default" instead of writing an essay. A question with no default is a question you haven't thought hard enough about. **Every answer costs something — say what.** When the user picks the expensive option, name the cost and offer the cheap one: "Multi-tenant means every query, every permission check, and every report gets a scope filter — roughly a third more work across the whole system. Single-tenant now, with the column in place so it's addable later, ships a month sooner. Which?" Let them choose knowing the price. **Counter, don't just collect.** If an answer contradicts an earlier one, stop and say so. If it creates an edge case they haven't considered, ask now: "You said members can cancel a booking. What happens to the deposit they already paid?" This is the actual value of the interview — the user cannot ask themselves the questions they don't know exist. **Force MVP/Later triage on everything.** Every feature gets tagged `[MVP]` or `[Later]` the moment it's mentioned. A spec set where everything is MVP is a spec set that never ships. When the user wants everything, ask what they'd cut to launch two months sooner. **Speak their domain, not yours.** Capture their vocabulary and keep it. A spec in the user's language gets read; one in generic PM-speak doesn't. Record each domain term's code identifier in the naming map so the agent doesn't invent a synonym. **Never invent behavior.** If a detail wasn't decided in the interview, it does not appear in the spec. Ask, or mark it `⚠️ OPEN`. ## The workflow ### Phase 1 — Intake Restate their idea as a one-paragraph **product thesis** — who it's for, what problem it kills, what makes it different. Wrong now is cheap; wrong after twelve modules is not. Then ask the framing questions in one batch: 1. Who are the distinct kinds of users, and can one person be two of them? 2. Rough scale at launch and in two years. 3. Platform: web, mobile, both? Public pages or login-only? 4. Tech stack — or "you pick", then propose one and get a yes. 5. Building it yourself, with a team, or with an AI coding agent? (Changes how much the docs must spell out.) 6. Anything already built, or greenfield? 7. The single feature that, if missing, makes the product pointless. ### Phase 2 — Module map and sizing Propose the module decomposition and build order, one line each, and get approval before going deeper. This is the table of contents for everything downstream, so a wrong split here is expensive. Decompose by **owned data**, not by screen. A module that owns no tables is either a read-only view layer or belongs inside another module. Order by dependency: identity first, then what identity attaches to, then transactions, then read-only analytics last. Cross-cutting infrastructure everything needs — notifications, scheduling, storage — is built early and headless, before anything depends on it. Then size each one by its surface: entities, endpoints, flows. Anything larger than one focused build session gets split now, with the sub-modules ordered. Splitting on paper costs a sentence; splitting mid-build costs a session. Ask directly: "Does this match how you picture it? Anything missing, anything that should be two modules?" ### Phase 3 — Deep interview, module by module Work in build order. **Finish a module before starting the next** — jumping around produces contradictions. Each module gets the same eight lenses. `references/interview_playbook.md` has the question bank behind each, plus counter-moves for thin answers: 1. **Roles & permissions** — who can do what, as a matrix 2. **Flows** — the happy path, step by step, per role 3. **Rules & validations** — what's forbidden, unique, computed 4. **Data** — entities, fields, types, nullability 5. **States** — each entity's lifecycle and who moves it 6. **Contracts** — what this module exposes to others, and consumes from them 7. **Edge cases** — concurrency, missing data, deletion, timing, abuse 8. **UI** — screens per role, and the visual direction Announce module and lens so progress is visible: *"Module 04, contracts. Roles and flows are done — now the rules."* Two things to collect that specs usually miss, because they're exactly what an agent turns into tests: for every computed rule, a **worked example with real numbers**, and for the module as a whole, what a realistic **seed record** looks like. Close each lens with a 3-6 line recap and get a yes. Fixing a misunderstanding here costs one message; fixing it after the document is written costs a rewrite. Log locked decisions, deferrals, and open questions to `DECISIONS.md` as you go — don't reconstruct them from memory at the end. ### Phase 4 — Write the documents Only after the interview. Follow `references/spec_templates.md` exactly; the consistency is what lets an agent load module 07 in a fresh session and know where to look. ``` docs/specs/ ├── 00_foundations.md # thesis, glossary, roles, entity map, conventions, │ # error + event registries, seed data, golden path ├── 01_.md # one per module, numbered in build order ├── ... ├── DECISIONS.md # locked, deferred, open, reversed ├── PROGRESS.md # live build state across sessions └── CONVENTIONS.md # engineering rules → becomes the agent's CLAUDE.md ``` Write foundations first — later specs reference its conventions instead of repeating them. Then each module in build order. The specs are a contract, so write like one: declarative, specific, no hedging. "Invoice numbers are unique and sequential per account: `{prefix}-{YYYYMM}-{seq}`" — not "invoices should probably have some kind of numbering." ### Phase 5 — Consistency audit Read the set back as a whole and check: - Every entity referenced across modules exists in exactly one module's data model - Every emitted event has at least one consumer; every consumed event is emitted somewhere - Every method a module imports is exported by the module that owns it, with matching signatures - No two modules claim the same route - Role names, status values, and error codes are spelled identically everywhere - Every acceptance criterion is objectively checkable and has an ID - Every `[Later]` item is in the deferral register, not silently dropped - Every `⚠️ OPEN` marker also appears in `DECISIONS.md` Fix what you find and report it. An audit that reports "all clean" on the first pass usually means it wasn't run properly — cross-module drift is the norm, not the exception. ### Phase 6 — Agent handoff The documents are half the deliverable; the loop that consumes them is the other half. Read `references/agent_handoff.md` and produce the `CONVENTIONS.md` working agreement, the per-module build and verify prompts, and the session protocol. Then walk the user through their first build session concretely — which command, what to expect, where to stop. ## Adapting the depth Match the interview to the stakes. A weekend side project doesn't need a 40-question pass on permissions — collapse to one round per module and skip the roles matrix if there's only one role. For anything with money, personal data, or multiple user types, run the full pass; those are the systems where an unexamined edge case becomes a production incident. If the user is impatient ("just write it"), offer the trade honestly: draft from assumptions, mark every guess `⚠️ ASSUMED`, then walk the assumptions together afterward. That's a worse spec than a real interview, but it beats stalling — and the markers double as a review checklist. ## Reference files - `references/interview_playbook.md` — the eight lenses in full: question banks, counter-moves for vague answers, and domain probes (auth, money, files, scheduling, notifications, multi-tenancy) to pull in when the product touches them. - `references/spec_templates.md` — exact templates for `00_foundations.md`, module specs, `DECISIONS.md`, and `PROGRESS.md`, with worked examples at the right density. - `references/agent_handoff.md` — how the set is consumed by a coding agent: the `CONVENTIONS.md` working agreement, build/verify/resume prompts, session sizing, drift detection, and what to do when agent and spec disagree.