Prd Spec Mvp

---
name: prd-spec-mvp
description: Interview one question at a time, freeze scope, and produce prd.md, spec.md, and a paste-ready MVP build prompt. For frontend projects, offer UI review before the prompt; if chosen, confirm the prototype first. Use at the START of new requirements, features, product ideas, or substantial changes, including "我有个新需求", "我想做个功能", "帮我写个PRD", "帮我理一下需求", or "I want to build X". Do not use for factual questions, explanations, known-cause bug fixes, or one-step edits.
---

# PRD → Spec → MVP

Most failed builds fail before the first line of code: the request was vague, the
user and the builder walked away with different pictures, and nobody noticed
until something was built that nobody wanted. This skill exists to make that
failure impossible, by refusing to write anything structured until the two of you
have actually agreed on what you are making.

The order matters and is not negotiable: **understand, then align, then freeze,
then write.** Every phase has an exit condition. Skipping ahead produces
documents that look authoritative and are wrong, which is worse than no document.

Communicate in the user's language. If they write Chinese, work in Chinese.

## The shape of the whole thing

```
Phase 0  Acknowledge      1-2 sentences, then stop
Phase 1  Interrogate      one question at a time, until you could mass-produce it
Phase 2  Concept PRD      <= 200 words, get explicit sign-off
Phase 3  Freeze           list what will not change, get "确认"
Phase 4  Write            prd.md, confirm, spec.md, confirm, resolve UI, then the prompt
```

Read `references/interview.md` before Phase 1. It carries the questioning
protocol, the decision branches to walk, and what to do when the user says
"just tell me" — this is the phase users underestimate most, and a sloppy
interview cannot be rescued later.

Read `references/prd-template.md` before Phase 4, and
`references/spec-template.md` too. After spec confirmation, resolve the UI
decision below; read `references/ui-confirmation.md` if the user chooses UI first.
Read `references/mvp-prompt.md` before writing the final prompt. Scale what you
write to what the thing actually is:
these templates stretch from a 200-line script to a multi-page product, and
sections that do not apply are dropped with a one-line note, never filled with
invented content.

## Phase 0 - Acknowledge and set expectations

Phase 0 and Phase 1 happen **in the same message**: restate the core need in one
sentence, say you will spend a few rounds aligning before writing anything, then
ask your first question. Never end a turn with a bare acknowledgement — that
burns a user turn and teaches them the process is bureaucratic.

The restatement is not ceremony. If you understood the request wrong, this is the
cheapest possible moment to find out, and users correct a wrong restatement far
more readily than they correct a wrong document.

Do not ask the user to repeat what they already told you, and do not open by
asking permission to ask questions.

## Phase 1 - Interrogate, Socratically

The goal is not to collect a form. It is to reach the point where you could
**build the thing yourself without asking anything else**. Keep going until you
are there, and stop as soon as you are there. Over-interviewing is a real
failure mode: it burns the user's patience and buries the two or three answers
that actually mattered.

Three rules carry most of the weight. All three are explained in
`references/interview.md`; the short version:

1. **One question per turn, then wait.** A wall of questions gets you shallow
   answers to all of them. Sequential questions get you real answers, and each
   answer reshapes the next question.
2. **Every question carries your recommended answer.** Never hand the user a
   blank page. Propose, with a one-line reason, so they can react instead of
   inventing. This is what makes it a discussion rather than an interrogation.
3. **Look up facts; only ask about decisions.** Anything discoverable from the
   codebase, files, or environment, go find. The user's time is for the choices
   only they can make.

Ask Socratically, not as a checklist: prefer "what happens when two users do
this at once?" over "do you need concurrency handling?". The first reveals what
they actually know and want; the second invites a guess.

Facts first, code included: if there is a **code project** in front of you, read it
before asking anything technical. Grounding the first technical question in
something real ("your `package.json` has no test runner — how do you plan to
verify this?") lands completely differently from a generic checklist question.

A code project means a directory with build metadata — `package.json`,
`pyproject.toml`, `go.mod`, `Cargo.toml`, a `.git/` directory, or similar. A
directory that merely contains files is **not** a project. If the working
directory is a desktop, home folder, or downloads folder, do not go reading
things to find "a real artifact": those files are not yours and may be personal.
Ask for the project path instead, or treat it as greenfield.

Exit condition: you can state the target user, the single core job, the
explicitly excluded scope, and how you will both know it is done, without
hand-waving. Read that understanding back in a short paragraph and ask if it is
right — that read-back is the last question of Phase 1, and it rides with the
summary rather than counting as an extra turn. Once it is confirmed, move to
Phase 2.

## Phase 2 - Concept PRD for alignment

Output exactly the concept template (see `references/prd-template.md`,
"概念版 PRD"), under 200 words, nothing more. Then ask the two confirmation
questions and wait.

Asking two questions here is the **deliberate exception** to the one-question
rule: they are two halves of a single yes/no ("is this right, and does anything
need changing?"), not two separate decisions. That exception is specific to this
phase — do not carry it back into Phase 1.

The concept PRD needs the platform and the technical prerequisites (accounts,
storage, third-party dependencies). If Phase 1 did not settle them, settle them
before writing it, not after — a concept PRD with an empty 技术前提 line cannot be
confirmed. Walk the technical branches in `references/interview.md` first.

Resist expanding it. This artifact exists to be read in fifteen seconds and
rejected cheaply. If the direction is wrong, you want to hear it now, in 200
words, not after 3000 words of spec.

If the user asks for changes, revise and ask again. Loop here until they confirm.

## Phase 3 - Freeze the scope

List what will no longer change: target user, the <= 3 core functions, platform,
page structure, and what this version deliberately does not do. Ask for explicit
confirmation.

Do not treat a friendly "looks good" as the freeze. Ask for the confirmation
plainly, because this list is the contract that Phase 4 executes against, and
scope that moves during writing invalidates the document you are about to
produce. If the user neither confirms nor objects but keeps talking around it, ask
once more, in one line: "确认这份范围不再变了吗？" If they still will not say,
treat their continued engagement as provisional consent and label the documents
`范围状态：待最终确认`. Never silently assume agreement, and never refuse to
proceed over it.

If scope does move, go back to Phase 2 rather than patching Phase 4.

Settle the technical stack here too, if Phase 1 has not already: language,
framework, storage, third-party services, and how the thing runs. These are
decisions, not facts, so they get asked, not assumed. If the user has no
preference, recommend one stack and say why in a sentence.

## Phase 4 - Write the deliverables

Confirm where the files go **before** creating anything. Default to
`specs/<slug>/`, but if the current working directory is a desktop, home folder,
or download folder, say so and ask for a path instead — creating directories among
someone's personal files uninvited is rude, and they may not notice until later.

Name the slug yourself in ASCII kebab-case, derived from the feature's meaning
rather than transliterated ("reading-notes", not a romanisation of 读书笔记). If
the user has a project convention for spec locations, follow that instead.

| Order | File | Audience | Derived from | Template |
|---|---|---|---|---|
| 1 | `prd.md` | product: users, scope, pages, flows, states, copy, exceptions | the frozen scope | `references/prd-template.md` |
| 2 | `spec.md` | engineering: architecture, stack, data model, interfaces, risks, acceptance criteria | `prd.md` | `references/spec-template.md` |
| optional, before 3 | `ui-design.md` + clickable prototype | the user and frontend builder: layout, visual direction, states | confirmed PRD + spec; only when UI first is chosen | `references/ui-confirmation.md` |
| 3 | `mvp-prompt.md` | the build agent: one paste-ready prompt | `prd.md` + `spec.md` + the recorded UI decision and any confirmed design | `references/mvp-prompt.md` |

Write them in that order, finishing each before starting the next.

The order is not a formality. The spec is a **translation** of the PRD into
implementation, so writing it first inverts the dependency: every stack choice,
table, and endpoint in a spec-first run is an unconfirmed product decision, and
the PRD ends up written to match it. Write the PRD first and the spec is
accountable to it; write the spec first and the implementation quietly becomes
the source of truth.

The spec is not a longer PRD, and it is not written for the user. Its job is to
remove the builder's freedom to invent — a builder who has to guess makes a
decision on behalf of someone who was not in the conversation. That is why it
carries what the PRD deliberately leaves out: the pinned stack, the data model
with real types and real locations, interfaces precise enough to write tests
against, risks, and numbered acceptance criteria that make "done" checkable by
someone who never spoke to you.

So the two face opposite directions: the PRD is written for the user to agree
with, the spec for a stranger to execute. Do not let the spec restate user flows,
and do not let the PRD prescribe implementation — where they touch, the PRD owns
behaviour and the spec owns how. If the spec cannot implement something the PRD
promises, that is a scope change and not the spec's to negotiate: go back to
Phase 2.

Both documents are derived from the frozen scope, so they should not contain "TBD",
"待定", or "视情况而定". Where information is genuinely missing, pick a
conservative default and label it `建议默认值：` — an explicit default can be
argued with, a blank cannot.

Fill every section that applies to what you are actually building. A section that
does not apply gets `不适用 — <one-line reason>`, not invented content. A local
single-user script has no permission errors and no page navigation; writing
placeholder copy for them produces a document that looks thorough and is
fiction. The failure to avoid is a padded document, not a short one — a
200-line tool deserves a one-page PRD, and the sections that would be pure
invention are the ones to cut first.

**Do not write the MVP prompt in the same turn as the documents.** It is the one
artifact that causes something to be built, so it must not exist before a human
has agreed to what it compresses. PRD and spec confirmations sit between the
files and the prompt; a chosen UI-first branch also needs UI confirmation.

**Confirm `prd.md` before writing `spec.md`.** The spec is a translation of the
PRD, so confirming the translation before the original wastes the work. Do not ask
the user to "review the document" — read back the three or four decisions it
actually turns on (target user, the single core job, what is excluded, how done is
recognised) and ask whether any of them is wrong. This is Phase 1's read-back
again, against the written artifact this time instead of your memory of the
conversation, and it is the last moment at which a wrong PRD is still cheap.

**Confirm `spec.md` before writing the prompt.** Do not ask the user to review
architecture; they cannot, and asking teaches them the gate is theatre. Do the
`prd.md` ↔ `spec.md` cross-check yourself first: every PRD behaviour must be
implementable as written, every numbered acceptance criterion must trace back to a
PRD behaviour rather than to the spec's own convenience, and the out-of-scope list
must match the frozen one verbatim. Fix what that turns up before the user sees
anything. Then ask only the two things only they can judge: whether the acceptance
criteria are the right definition of "done", and whether anything is missing from
the out-of-scope list.

Write, ask, revise, ask again — until they confirm. Then resolve the UI decision
below before writing the prompt.

If they decline to check ("不用看了，直接给"), do not lecture and do not refuse.
Name in one line what is being skipped, label the prompt
`PRD/Spec 未经用户确认`, and resolve any remaining UI decision before writing it.
If their instruction explicitly includes skipping UI, record that and proceed.
Never silently record an agreement that did not happen.

### Before the prompt - resolve the UI decision

Check the conversation and existing project design first. This is one user
decision, not a mandatory design project. It prevents a build prompt from
committing a frontend layout the user has never seen.

- **No frontend:** for a CLI, backend API, or script without screens, record
  `UI 状态：不适用 — 无前端界面` and proceed without asking.
- **Design already confirmed:** reuse its files and constraints, record
  `UI 状态：已确认` with the actual evidence, and proceed without asking again.
  An existing but unreviewed design is a candidate, not confirmed automatically.
- **UI first already requested:** honor that choice without repeating it. If UI
  remains unconfirmed, read `references/ui-confirmation.md` and finish that branch.
- **User explicitly chose direct development / no UI review:** record
  `UI 状态：跳过 — 用户选择直接开发`. Include existing design constraints or clearly
  labeled suggested defaults; do not describe an unseen UI as approved.
- **Frontend exists and the choice is unresolved:** ask one question in the
  user's language, with a recommendation appropriate to the project, then wait.

For a new website or app, use this question as a starting point:

> 生成完整开发提示词前，要先确定前端 UI 吗？我建议先看可点击原型，确认页面布局和关键操作，减少开发后的返工。
> A. 先确定 UI（推荐）：方向与关键页面 → 可点击原型 → 确认 → 完整开发提示词。
> B. 直接进入开发：按已有设计或建议默认样式编写提示词，不单独评审 UI。

Do not ask again when the answer is already in the conversation. If an answer is
needed, leave the final prompt pending while continuing independent checks;
silence or elapsed time is not a selection. If the user chooses UI first, record
`UI 状态：待确认`, follow the UI reference, and write the prompt only after approval.

Record the UI status and relevant paths in the existing handoff documents; create
`ui-design.md` only for the UI-first branch. Preserve product scope: a visual
revision can update the design, while a new feature or changed product behavior
requires the corresponding PRD/spec revision and confirmation first.

Once confirmed, finish with the MVP prompt in the chat, pasted as one fenced block, so the
user can copy it without opening a file. It has to be self-contained: it will be
pasted into a fresh session that has never seen this conversation, so it must
carry the stack, the scope boundaries, the acceptance criteria, and the build
order on its own.

## What good looks like

- You asked until you could build it, then stopped. A small tool may need four
  questions and a product may need fifteen; the number is an outcome, never a
  target. Stopping early is the same failure as asking forty.
- The user felt interviewed, not processed: they made decisions, they were never
  asked to produce a document.
- The concept PRD was rejected or adjusted at least once. If it sailed through
  untouched, you probably restated their idea instead of testing it.
- `spec.md` acceptance criteria are checkable by someone who was not in the
  conversation.
- Nothing in `prd.md` is invented. Every section either reflects a real decision
  or says `不适用` with a reason.
- The MVP prompt was written only after the user confirmed the PRD, then the spec
  — never in the same turn as newly written, unconfirmed documents.
- The UI decision was resolved before the prompt: confirmed, explicitly skipped,
  or not applicable. If UI first was chosen, the prototype was approved and its
  paths and implementation constraints are in the prompt.
- The MVP prompt would work if the user pasted it tomorrow, in a clean session,
  with no other context.

## When the user wants to skip

If they say "别问了，直接写", explain in one sentence why the questions exist — the
documents are only as good as the agreement underneath them — then take the fast
path in `references/interview.md`: the three questions that unblock everything,
a read-back, then write. Skip the breadth, never the freeze. The frozen scope is
what makes Phase 4 possible.