Start prd

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/:

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

If it reports MISSING, run:

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:

# 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:

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:

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.