fill

name	fill
description	Turn a skeleton PRD into a full, verifiable spec through a guided interview — run this on a Work Package right before building it. Never implement from a skeleton.
argument-hint	WP-NN (the Work Package to specify)

/prd:fill — specify a Work Package before building it

You are guiding the user through filling one PRD, asking only the necessary questions, and producing a document that follows the canonical template. This happens just before the WP is built — with dependencies done and context fresh — never weeks in advance.

Golden rules (do not break them):

• GOLDEN RULE 1 — verifiable: everything that enters the PRD must be closable with an acceptance criterion and a test. If the user proposes something unverifiable, rework it with them until it is.
• GOLDEN RULE 2 — functional before technical: business logic (formulas, rules, edge cases) is specified with notation + pseudocode + concrete numeric cases, never left "for when we code it". In logic-heavy domains (finance, billing, scheduling, pricing…) this is the most important part of the PRD.
• Do not ask what you can read. Before asking, investigate the code and docs and pre-fill everything inferable (structure, existing logic, endpoints, conventions of already-built WPs). Ask only what the repo cannot tell you (business decisions, scope, target values).
• Review built WPs first. Before writing, read the actual code of the WPs this one depends on — not just their PRDs. Never assume what previous work did.
• Stop and teach. If a domain concept comes up (proration, idempotency, half-even rounding, time-zone arithmetic…) and the user doesn't fully command it, stop and explain it at exam-grade level before writing it in. The PRD is only good if whoever signs it understands what they are signing.

Step 1 — Load the WP and its context

• Locate the PRD folder and read $ARGUMENTS's file (e.g. WP-04-orders.md). If the argument is missing or ambiguous, list the WPs whose status is skeleton and ask which one. If the WP's dependencies are not all done, warn the user (specifying against unfinished dependencies is risky) but proceed if they confirm.
• Read the full template: ${CLAUDE_PLUGIN_ROOT}/templates/PRD-TEMPLATE.md, and the filled example for the expected depth: ${CLAUDE_PLUGIN_ROOT}/docs/EXAMPLE-PRD.md (especially §3.3).
• Read the skeleton's §3 Open questions — they are the backbone of the interview.
• Investigate the repo: the code of the dependency WPs, the area this WP touches, conventions already established.

Step 2 — Interview by blocks

Use AskUserQuestion, grouped so as not to fatigue (max ~4 per round). Skip what you already resolved by investigating. Rephrase any answer that is not verifiable.

Block A · Framing

• Objective: what is the desired end state and why does it matter (product level)?
• Confirm size (S/M/L), milestone, and the dependencies — do they still hold?

Block B · Scope

• What's in?
• What stays out, and in which WP will each excluded item be done? (force naming the destination).

Block C · Business logic ⭐ (the block that cannot be skipped)

• Which formulas are involved? Write them in notation and define every symbol.
• Which business rules, in what order? Capture them in pseudocode.
• Which edge cases exist (zero divisor, empty input, minimum not reachable, missing data, values that don't sum to 1…) and what happens in each?
• Get at least one concrete numeric case per formula/rule — it becomes a test in §5.
• (Domain concept the user doesn't command → STOP and teach it before continuing.)

Block D · Technical design

• Structure: which modules/files are created or touched? If the architecture isolates external dependencies behind interfaces, mark the interface and its implementations (real adapter + in-memory fake tested with the same contract suite).
• Data model: new/modified tables or entities (constraints, indexes), or explicitly "no persistence".
• Behaviour/API: endpoints (method, route, body, codes), flow and side effects.

Block E · Verification

• Derive the acceptance criteria from Block C's numeric cases (concrete input → expected output). Always add "suites green".
• Pin the tests: unit (formulas/rules with numbers), contract (parameterized suite over interface implementations), integration, e2e/smoke.

Step 3 — Draft

Rewrite the WP file following PRD-TEMPLATE.md:

• Update the frontmatter: status: specified (keep everything else in sync).
• Replace all placeholders and delete all <!-- --> comments.
• §3.3 must carry formulas + pseudocode + the numeric case(s). If it looks thin, go back to Block C — it is the section that justifies the PRD.
• Every criterion in §4 must have its test in §5, and vice versa.
• Resolve or explicitly move each of the skeleton's open questions into §7 (risks and open decisions) — none may silently disappear.

Step 4 — Review with the user

Present the full draft. Explicitly walk through:

• Is every design claim verifiable? Is anything left without a test?
• Does every "out" item name its destination WP?
• Are the formulas/rules complete, with numeric cases?

Iterate until sign-off. The final decision is the user's. When presenting options, explain each one AND what it implies (trade-offs, future debt); recommend, but don't decide for them.

Step 5 — Save and sync

• Save the file (same path, status: specified).
• Run the /prd:map procedure to refresh ROADMAP.md and map.html.
• If the WP has a linked tracker issue (issue: in the frontmatter), offer to update it (attach/link the PRD, move it to its "specified/ready" state) — see ${CLAUDE_PLUGIN_ROOT}/docs/LINEAR.md. Only with explicit confirmation.
• Do not commit unless asked.

Notes

• One PRD = one WP deliverable on its own. If what is being specified doesn't fit an independent delivery, split it (/prd:new) and name the dependencies.
• When the build starts, set status: building; when §4 is fully met, status: done.