start-prd

---
name: start-prd
description: Bootstrap a `.anvil/prd.md` draft from a rough project idea — interview the user question-by-question and write the result so `anvil prd parse` can consume it. Use this skill when the user has a project intent but does not yet have a PRD (e.g., asks to "start a PRD", "draft requirements", "author a PRD", or "spec out a project").
---

# Start a PRD — Rough Idea to PRD Draft

Produce a parseable PRD from an unstructured prompt by interviewing the user one question at a time. This skill writes `.anvil/prd.md` — it does not parse, review, or approve. Those steps belong to the `prd` skill.

---

## When to Use

- The user has an idea ("I want to build a CLI that converts CSV to Parquet") but no PRD yet.
- `anvil status` reports `PRD: none` (or `anvil status --hook-format` shows `prd-status:none`) and the user is not ready to write the template by hand.
- A rough scope was discussed in chat and now needs to be captured as a structured document.
- The user explicitly asks to "start a PRD", "draft requirements", "author a PRD", or "spec out" a project before planning.

**Do not use this skill** to parse, review, or approve a PRD that already exists — use the `prd` skill. **Do not use this skill** to score, plan, or expand tasks — use the `plan` skill. **Do not use this skill** when the user already has a complete `prd.md` in hand and just wants it loaded into state.

---

## Prerequisites

Before running `anvil status`, `anvil init`, or any other state command, resolve
the actual `anvil` executable with the runtime's native lookup and run
`anvil prd source-name --help`. Require exit 0; matching version text alone is
not capability proof. If the help probe is absent, run `anvil --version` and
stop before changing anything. Report: "Cannot safely resolve the selected PRD.
`<executable>` reports `<version>` but does not expose
`anvil prd source-name`, required by this skill and shipped in
`anvil-state >=0.6.1`. No PRD file or state was changed. Upgrade with
`uv tool upgrade anvil-state`, refresh the Anvil plugin if applicable, restart
the harness/MCP process, then verify `anvil --version` and
`anvil prd source-name --help`. I will not infer a filename, parse, or delete
state."

After that capability gate succeeds, confirm initialization through the CLI.
State lives in the HOME workspace by default
(`~/.anvil/workspaces/<key>/.anvil/...`), not in an in-repo `.anvil/`:

```bash
anvil status >/dev/null 2>&1 || echo "MISSING: run anvil init first"
```

If it reports `MISSING`, run:

```bash
anvil init --name "<project-name>"
```

The early gate ensures an older CLI cannot create state before the skill stops.

---

## Workflow

### Step 1 — Interview the user

Run the interview directly. Ask one question per message. Wait for the answer before asking the next.

**Question 1 — The rough idea.** Open with:

> What are you building? A one or two sentence pitch is enough — we will refine from there.

Capture the user's answer verbatim. This becomes the seed for `## Summary`.

**Question 2 — Target users.** Ask:

> Who is this for? Internal team, external developers, end users, yourself?

The answer feeds the `## Summary` paragraph and may shape `## Non-Goals` (if the answer narrows the audience).

**Question 3 — Primary success criterion.** Ask:

> If only one thing has to be true for this project to be considered a success, what is it?

This becomes the lead bullet in `## Goals` and often the lead bullet in `## Acceptance Criteria`.

**Question 4 — Key non-goals.** Ask:

> What is explicitly out of scope for this version? Even "none declared" is a valid answer — but stating non-goals up front prevents the planner from sprawling.

This populates `## Non-Goals`. Push back gently if the user says "nothing" — most non-trivial projects have at least one obvious exclusion (e.g., "no auth in v1", "single-user only").

**Question 5 — Must-have features.** Ask:

> What are the two or three things this absolutely must do? Bullet form is fine.

Each item becomes a candidate `## Features` entry (or a `## Requirements` bullet if it is small enough to express as a single requirement).

**Question 6 — Risks and unknowns.** Ask:

> Are there any known risks, unknowns, or decisions you have not made yet?

The answer populates `## Risks` and `## Open Questions`. If the user says "none", record an empty section rather than skipping it — the visibility of "no risks identified" is itself useful information.

**Question 7 — Release / milestone (optional).** Ask:

> Is this PRD scoped to a specific release or milestone (e.g. `v0.2.0`, optionally a tag)? A project can hold several release-scoped PRDs side by side. Leave blank for the single default PRD.

Choose the canonical ID before resolving any path. A non-empty answer becomes
the `**Release:**` field in the draft (the parser pulls it into
`PRD.target_version` / `target_tag`). It does **not** auto-derive the `prd_id` —
the parser takes `prd_id` only from the `--prd` flag, never from the Release
text. Choose a short canonical `prd_id` (for Release `v0.2.0 (tag: v0.2)`, pick
`v0.2`). A blank answer selects the default PRD (no `**Release:**` line and no
`--prd` flag).

#### Required `prd source-name` resolver preflight

Before any branch that reads, backs up, edits, writes, or parses a PRD, rerun
`anvil prd source-name --help` with the executable proven in Prerequisites, then
run `anvil prd source-name [--prd <id>] --json` with that exact selected ID.
Require exit 0, `ok: true`, and a non-empty `data.relative_name`.
Retain that validated value as `PRD_RELATIVE`; it is the sole relative path for
the selected PRD for the rest of this run. Do not resolve it again unless the
selected PRD ID changes, in which case repeat this entire preflight.

If the capability exists but the resolver returns a typed state-root, identity,
or legacy-source migration error, surface that exact error and stop. Do not
mislabel it as version skew and do not construct a fallback filename.

Use the same selected `prd_id` for the resolver and the later parse.

**Stop at seven questions unless something material remains unclear.** Asking more questions than necessary fatigues the user and rarely improves the draft. If the answers are sparse, ask a single follow-up before moving to Step 2 — do not chain three more questions to "fix" thin input.

### Step 2 — Generate the PRD draft and show it to the user

Compose a draft that matches the structure in `docs/prd-template.md` (relative to the plugin root). The minimum draft uses the four required sections plus `## Non-Goals` and `## Acceptance Criteria`:

```markdown
# Project: <Name extracted from Question 1>

## Summary

<One paragraph synthesized from Questions 1 and 2.>
**Release:** <Only when Question 7 was answered, e.g. `v0.2.0 (tag: v0.2)`. Omit this line entirely for the default PRD — the parser pulls it out of the summary into PRD.target_version / target_tag.>

## Goals

- <Primary success criterion from Question 3.>
- <Each must-have feature framed as a goal statement.>

## Non-Goals

- <Each non-goal from Question 4, one per bullet.>

## Requirements

- R001: <First atomic "the system must..." statement, derived from must-have features.>
- R002: <Second atomic requirement.>
- R003: <...>

## Acceptance Criteria

- <Verifiable statement matching the primary success criterion.>
- <Additional verifiable statements covering each must-have feature.>

## Risks

- <From Question 6, or "none identified" as a single bullet.>

## Open Questions

- <From Question 6, or "none identified" as a single bullet.>
```

Add a `## Features` section only when the user named distinct groupings. Add a `## Tasks` section only when the user asked for hand-authored tasks; otherwise let `anvil plan` generate them later.

### Step 2a — Optional behaviour-first challenge mode

Do **not** add another interview by default. If the user explicitly asks to be
challenged (for example, “challenge this PRD” or “use challenge mode”), run
`anvil prd assess` after the draft is written and parsed. Ask only the
highest-value advisory question, one at a time. For each answer, let the user
clarify the PRD, explicitly defer it, or accept a documented `## Assumptions`
entry with a stable `A###` ID, rationale, and affected requirements.

If the user explicitly asks to continue autonomously, do not ask assessment
follow-ups. Record only bounded, reversible inferences in `## Assumptions`,
re-parse and re-assess, then report remaining advisories before continuing.
Stop instead when an inference needs external authority, conflicts with declared
scope/non-goals, or has no bounded safe default. This does not change the
separate human approval step.

**Show the draft to the user before writing.** Present the full proposed `prd.md` content inline (or as a fenced markdown block) and ask:

> Here is the PRD draft I assembled from your answers. Does this look right? Reply with edits or "looks good" to write it to the workspace (the per-PRD file formed from the `.anvil` directory `anvil status` echoes plus the preflight's retained `PRD_RELATIVE`).

Wait for explicit approval. Apply any requested edits in-place and re-present until the user accepts.

### Step 3 — Write the PRD into the workspace

The PRD does not live in an in-repo `.anvil/`, and its filename depends on the
`prd_id` selected after Question 7 — **never hardcode it.** Resolve the layout-aware
directory first: `anvil status` echoes a `Path:` line pointing at the active
`.anvil` directory (in the HOME workspace by default). Capture the directory and
ask the CLI for the portable relative name, then join them:

```bash
ANVIL_DIR=$(anvil status | sed -n 's/^Path:[[:space:]]*//p')
# PRD_RELATIVE is the validated data.relative_name retained by the preflight.
PRD_FILE="$ANVIL_DIR/$PRD_RELATIVE"
```

Once the user has approved the draft, check whether a PRD already exists at the
resolved `$PRD_FILE`:

```bash
test -f "$PRD_FILE" && echo EXISTS
```

**If the file exists**, do not overwrite without confirmation. Show the user a one-line summary of the existing file (first heading, line count) and ask:

> A PRD already exists at `$PRD_FILE`. Overwrite it with the new draft? (yes / no / save-as-backup)

- On `yes`: write the new draft to `$PRD_FILE`.
- On `no`: stop. Tell the user the draft was not written; offer to save it to a sibling path (e.g., a `.draft.md` next to it).
- On `save-as-backup`: copy the existing file to `$PRD_FILE.bak` first, then write the new draft to `$PRD_FILE`.

**If the file does not exist**, write the draft directly to `$PRD_FILE` (create the `prds/` directory first for a named PRD).

### Step 4 — Parse the draft and continue into the `prd` skill

After the file is written, drive the parse inline rather than handing the user a list of CLI commands to run. The user just approved the draft content — asking them to also run `anvil prd parse` themselves adds friction without adding value.

Confirm the parse and run it:

> Draft written to the workspace (`$PRD_FILE`). Ready to parse it into `state.db`? (yes / no / let me edit first)

- **On `yes`**: invoke `anvil prd parse` for the default PRD, or `anvil prd parse --prd <prd_id>` for a named release PRD (via Bash, the MCP `parse_prd` tool when available, or whichever tool the runtime exposes). It reads the resolved per-PRD file and prints a count line plus a stable `PRD source:` identity. Surface the result inline. The user sees the parse output in the same conversation, not after a context switch. For example, `anvil prd parse` prints:
  > Parsed 6 requirements, 3 features, 8 tasks.
  > PRD source: default

  Then ask: Any unexpected counts? The next step is `prd review`, want me to drive that with you now? (yes / not yet)
- **On `no`**: stop. Confirm the file is on disk (at the resolved `$PRD_FILE`) and tell the user it is theirs to refine.
- **On `let me edit first`**: wait. When the user signals they are ready, return to the confirm step above and run the parse.

When the user says yes to continuing into review, hand off to the `prd` skill **by invoking it directly** — do not paste a CLI to-do list. The `prd` skill is designed to drive the `review` → `approve` flow conversationally, with the same one-question-at-a-time discipline this skill uses.

See `/anvil:plan` for the canonical anti-pattern statement on driving commands inline versus handing off CLI lists. **When to actually hand off:** if the user explicitly opts out, or if the runtime lacks the required tool. Otherwise, drive.

---

## Anti-Patterns

- **Asking 20 questions at once.** A wall of questions produces a wall of one-word answers. Stay strictly at one question per message — even if it feels slow.
- **Writing the PRD without showing the user a draft for review.** The interview answers are raw input; the translation into PRD bullets is interpretive. Always show the draft and wait for explicit approval before writing the file.
- **Overwriting an existing workspace `prd.md` without confirmation.** A silent overwrite can destroy a hand-authored PRD that took hours to craft. Resolve the path the CLI echoes (`anvil status` `Path:` line), check for an existing file, and prompt before clobbering.
- **Assuming the PRD lives in an in-repo `.anvil/`.** State is in the HOME workspace by default. Never `ls`/`cat`/`test` a literal in-repo `.anvil/prd.md`; resolve the path from `anvil status` (the `Path:` line) or let `anvil prd parse` find it.
- **Parsing without first showing the user the assembled draft.** The user must approve the draft content in chat before you write and parse it. Once approved, driving `anvil prd parse` inline (Step 4) is the intended flow; do not make the user run it by hand.
- **Skipping `## Non-Goals` because the user said "none".** Record "none identified" as an explicit bullet instead of omitting the section. Visibility matters for the planner and for reviewers.

---

## Composition with Other Skills

| Position | Skill |
|---|---|
| Before this skill | Usually none — start-prd is the entry point when no PRD exists |
| After Step 3 (file written) | `prd` — parse, review, and approve the draft |
| After `prd review --approve` | `plan` — generate features, tasks, and scores |

---

## Notes

This is a skill, not a CLI command; there is no `anvil start-prd`. The
seven-question interview is pure markdown choreography, and every CLI surface it
uses ships today: `anvil init`, `anvil status`, `anvil prd source-name`, and
`anvil prd parse`. Invoke it via
`/anvil:start-prd`.

• SKILL.md 14 KB
• agents/openai.yaml 1 KB