AI PRD: write requirements a model system can actually be held to

A PRD for an AI system is a different document. Your requirements are not instructions to an engineer; they are constraints on a system that will improvise. This skill restructures the document around that fact.

Files this skill drives

• ../../templates/definition/prd.md, the base PRD template
• The AI overlay in templates/ai/: eval-spec.md, guardrails.md, hallucination-controls.md, human-approval-gates.md, prompt-structure.md, context-management.md, red-team-review.md, and for agentic systems agent-architecture.md and multi-agent-workflow.md
• For regulated contexts: ../../modules/regulated/templates/regulated-ai-prd-template.md, driven by ../../modules/regulated/SKILL.md

When to use

• Specifying any feature where an LLM, agent, or model makes or drafts a decision
• Reviewing an existing PRD that says "the AI should..." anywhere
• Turning a demo into something an engineering team can be accountable for

The five sections this skill enforces

1. Acceptance criteria are eval sets, not sentences

"The agent should extract the merchant name" is a wish. A requirement is:

• A labeled example set (minimum 30 to 50 cases for a first release)
• A pass threshold stated as a number (accuracy, recall at k, or judge score)
• The rule for what happens below threshold (block release, not "review")

For every "should" in the draft, ask: where is the example set, what is the number, who owns adding failing cases back into the set. Capture the answers in ../../templates/ai/eval-spec.md.

2. Edge cases are the spec, not the appendix

The happy path is what the model does for free. The document earns its keep at the boundaries. Require explicit tables for:

• MUST REFUSE: inputs the system declines (out of scope, unsafe, ambiguous beyond repair)
• MUST ESCALATE: conditions that route to a human, with the routing target named; capture triggers and timeout behavior in ../../templates/ai/human-approval-gates.md
• MUST NEVER INVENT: fields where fabrication is worse than absence (numbers, names, legal or regulatory statements, monetary amounts); the abstain policy lives in ../../templates/ai/hallucination-controls.md

3. Non-determinism goes in writing

The same input can produce a different output tomorrow. The PRD must state:

• Which output variations are acceptable (wording? ordering? formatting?)
• Which are defects (different decision, different number, different refusal behavior)
• Reproducibility posture: temperature and seed policy, and whether logs capture enough to replay any decision

If the PRD does not say this, QA will decide it later, in a bug tracker, angrily.

4. Guardrails are features with owners

Each guardrail gets a row in ../../templates/ai/guardrails.md: name, trigger, behavior, owner, test. Minimum set to consider for any agentic feature:

• Fail-closed on unverifiable output (cannot check it = do not ship it to the user)
• Human approval before anything irreversible (sends, payments, deletions, postings)
• Spend and rate caps with a stated ceiling and a stated behavior at the ceiling
• Input isolation: content the system reads is data, never instructions
• Audit trail: who or what decided, based on which inputs, at which model version

5. The operations page

• Cost per call target and the alert threshold
• Latency budget per step
• Model version pinning and the upgrade decision process
• Telemetry: what is logged per decision, where evals run (CI, pre-release, production sampling), and the rollback trigger

The regulated route

Generic PRD tooling writes the five sections above and stops. When the product sits under a financial or data regulator, do not run this skill's own overlay from memory. Start instead from the byte-exact template at ../../modules/regulated/templates/regulated-ai-prd-template.md, follow ../../modules/regulated/SKILL.md, and complete its section 0 (license preconditions, scheme rules, data residency and vendor terms, financial-crime touchpoints, conduct, the audit-proof metric) before any requirement is written. A blank overlay field is a decision deferred to whoever finds it blank. Regulator names, section numbers, and quoted text come only from that module or from primary text the user supplies; never invent them.

Inputs

The discovery evidence and the problem statement a normal PRD would need, plus four things this skill cannot proceed without. What the model is actually being asked to decide or produce, stated as the user's outcome rather than the capability. Whether a person sees the output before it has an effect, and who that person is. The data the system reads at inference time, and where it came from. And a labelled set, or the plan and owner for building one, because acceptance criteria here become eval cases and there is nothing to write without examples. Ask for these when they are missing rather than drafting around them. Two conditions stop the work outright: if a financial or data regulator governs the product, route through reg-gap-check and the regulated module before another section is written, and if the implementer turns out to be a human engineering team after all, this is the wrong skill and write-prd is the right one.

Workflow

1. Classify the context. Regulated: take the regulated route above, then return here for sections the module does not cover. Unregulated: start from the document at the weight already chosen, prd.md or one-pager.md; the overlay sections below attach to either.
2. Read the draft PRD, or interview the PM if starting blank.
3. Rewrite every "should" statement into the section-1 form. List the ones that cannot be turned into evals; those are not requirements yet, flag them.
4. Build the three edge-case tables. Push for at least 5 rows each; empty tables mean discovery is not done.
5. Write the non-determinism clause and the guardrail table.
6. Produce a one-page GAPS list: every place the original document assumed a deterministic implementer, ranked by blast radius.

Output format

Return the restructured PRD with the five sections, then the GAPS table:

Failure modes this skill guards against

• Acceptance criteria that cannot be evaluated. "Responds helpfully and accurately" as a pass condition. Helpful is not measurable, so nothing can be said to have failed, and it ships anyway.
• Non-determinism discovered at launch. The document treats output as fixed, and latency, cost and the interface were all designed around one answer that the model does not reliably give.
• Guardrails left to the prompt. "Should not hallucinate" written with no owner, no measurement and no escalation path, which makes it the on-call engineer's problem at three in the morning.
• An eval set built from demos. Cases cherry-picked from examples the team already watched work, so distribution shift, adversarial input and edge personas all surface in production first.
• Capability described instead of product. The document says what the model can do rather than what the user gets, and the implementer optimises for the benchmark rather than the workflow.

Exit gate

This skill's output feeds Gate 2 in ../../os/STAGE-GATES.md. Do not report the PRD done while any requirement lacks a numeric pass condition, any guardrail lacks an owner and a test, or any GAPS row lacks an owner and a date.

What checks this

Some checks on this skill run automatically and some depend on a person. This section says which is which. It is generated by python3 tools/what_checks.py from the declarations it links to, and CI fails when it falls out of date.

• Checked by CI on every commit. This file must carry the seven sections every prose skill carries: python3 tools/skill_rubric.py --min 7 fails the skill-rubric gate in python3 tools/ci_gate.py when one is missing. That checks structure, not whether the advice is right.
• Checked by the runtime. This skill is declared against Gate 2 in SKILL.graph.yml. Gate 2 is recorded with pmos gate --bank-id define, which refuses the proof unless every question in that bank has been accepted and the bank is the current one, requires the proof to name its source, source_sha256, actor_id, requester_id, decision and approved_at, and rejects self-approval and any approver the bank does not pin. Approver ids are typed, not authenticated, so a recorded approval is a local attestation, not proof of who signed. If the proof's source changes after approval the gate goes stale and nothing later completes until it is proved again. The journey run shows all six gates and a stale gate being proved again.
• Checked by a person. The runtime checks who approved and that the evidence has not changed. It does not check whether the reasoning in this skill's Workflow was followed well; that judgment belongs to the people who sign the gate. Gate 2 is signed by the product owner, the engineering lead, the business sponsor and the regulatory owner (regulated products only), per the sign-off tables in os/STAGE-GATES.md.