Prompt Specs, Not PRDs — High Peak Studio

PRDs are great at shipping deterministic software. AI products are stochastic, conversational, and learn by showing, not telling. If you’re still writing PRDs to ship agentic systems, you’re optimizing for the wrong failure modes.

PRDs fail where AI-native products live

Traditional PRDs assume a stable system: inputs, deterministic logic, outputs. They shine when you need precise interfaces and predictable behavior. In AI products, behavior is emergent, context-heavy, and fluid across versions of models, data, and tooling. The spec you write in week one is obsolete by week two.

PRDs also force a surface-first mindset. You invest weeks on routes, states, and error codes while the core experience—how the model thinks, asks, and answers—remains under-specified. That’s like building a skyscraper’s lobby and guessing how the elevators might work later.

Most importantly, PRDs separate the “what” from the “how” in a way that’s harmful to AI systems. In model-driven software, behavior is the product. Your scaffolding, prompts, tools, and evaluations form the code path. A conventional PRD can’t represent the moving parts you actually need to lock down.

AI-native products don’t need more wireframes. They need operationalized behavior: a living contract that defines how the model reasons, calls tools, and proves it did what you intended.

Define the new artifact: the Prompt Spec

A Prompt Spec is a product artifact that treats language, tooling, and evaluation as first-class code. It’s not “prompt engineering notes.” It’s an executable contract that governs how an agent thinks, asks, acts, and validates its work—versioned, testable, and reviewable like any other critical component.

Where a PRD lists requirements and acceptance criteria, a Prompt Spec lists reasoning modes, canonical prompts, tool affordances, structured outputs, and test suites. It also defines red-team prompts, boundaries, and recovery strategies. It’s designed for iteration: tiny changes, measurable impact, quick rollback.

The Prompt Contract vs. the Product Contract

The Product Contract says, “Users can file expenses, and an admin can approve them.” The Prompt Contract says, “The agent interprets ambiguous receipts using a two-pass extraction, asks one clarifying question if confidence is below 0.7, and stores structured JSON with explicit ‘assumed_fields.’” The second is actionable, measurable, and extensible. It’s the difference between describing a system and governing an intelligence.

From copy to computation

Most teams still treat prompts as copy. That’s a liability. Prompts are computation: they set objectives, constraints, and control flow. A Prompt Spec wraps that computation in a structure that can be linted, versioned, and continuously evaluated.

System intent: Why the agent exists and what it must never do.
Roles and tone: Behavioral stance under different contexts.
Canonical prompts: Core instructions with slots and templates.
Tooling contract: Which tools exist, how to call them, and when.
Memory policy: What to remember, for how long, under which rules.
Output schemas: Strict formats, JSON shapes, and examples.
Safety rails: Blocks, de-escalation flows, and human handoff.
Evaluation harness: Goldens, fuzzers, red-teaming, and metrics.
Observability: Traces, counters, costs, and failure taxonomies.

The PROMPT Spec Framework

At High Peak, we use a simple model to author and review Prompt Specs: PROMPT—Purpose, Roles, Orchestration, Metrics, Prompts, Tooling & Data. It’s fast to fill, hard to ignore, and battle-tested across agentic products.

P: Purpose

Define the job-to-be-done and the failure posture. What is the agent optimizing for? What should it never guess? Include the “North Star” and the “Red Lines.”

Objective: One sentence, measurable.
Scope exclusions: Explicitly out-of-bounds topics and tasks.
Risk posture: Conservative, neutral, or aggressive behavior.

R: Roles

Agents wear hats. Name them. Codify tone, authority, and escalation triggers for each role, not just generic “assistant.” This unlocks predictable context switching.

Primary role: E.g., “Finance Controller.”
Sub-roles: E.g., “Data Extractor,” “Policy Enforcer,” “Investigator.”
Role transitions: How and when to switch, with guardrails.

O: Orchestration

Specify control flow and planning. When to call tools, how to retry, when to ask the user, and how to reflect. Capture multi-agent coordination if relevant.

Planning mode: Single-pass, reflect-then-act, or multi-agent debate.
Tool call policy: Preconditions, cool-downs, and cost caps.
Memory policy: What to store and retrieve, keyed by purpose.

M: Metrics

Behavior without measurement is vibes-only. Pick metrics that tie to outcomes, not vanity. Bake them into the spec so CI can enforce regressions.

Assistance rate: % of tasks completed without human edits.
First pass yield (FPY): % good on first try within cost/latency SLOs.
Hallucination rate: Verified factual errors per 100 tasks.
Escalation precision/recall: Right calls to hand off vs. missed ones.
User satisfaction proxy: Thumb score, dwell time delta, NPS-lite.

P: Prompts

Canonicals, variants, and slot maps. Include few-shot examples for tricky edges, and red-team negatives. Version each with change notes.

System prompt: Immutable core intent and constraints.
Developer messages: Operational instructions, evaluators, schemas.
Few-shot sets: Positive, adversarial, and off-distribution examples.

T: Tooling & Data

List tools with contracts, define result schemas, and declare external data dependences. Tie to cost budgets and fallback plans.

Tools: Name, arguments, return types, expected latency, budgets.
Data contracts: Source, freshness, PII/safety posture.
Fallbacks: What to do on timeouts, errors, or missing data.

The Four Dials: a control model for behavior

We also use a lightweight operational model: the Four Dials—Creativity, Fidelity, Agency, Memory. Each dial is a bound you can set per task. This makes tradeoffs explicit and operationally tunable.

Creativity: Temperature, top-p, and paraphrase budget.
Fidelity: Citation requirements, grounding rules, and references.
Agency: Tool access scope and maximum action depth.
Memory: Context window size and retrieval depth.

A Prompt Spec should declare default dial settings, plus overrides by role or task. This prevents silent drift and aligns UX with risk. Operators can raise or lower dials as risk or cost change without rewriting everything.

Anatomy of a Prompt Spec: three concrete scenarios

Scenario 1: Relay Inbox — AI email triage for sales teams

Relay Inbox is a product that reads inbound leads, classifies them, drafts replies, and updates the CRM. The old PRD covered labels, buttons, and syncs. It didn’t say how to handle partial data, unclear intent, or missing context. A Prompt Spec turns that mush into a contract.

Purpose: Maximize timely, accurate triage and first-response quality; never promise pricing without SKU confidence >0.9.
Roles: “Intake Classifier,” “Reply Drafter,” “CRM Updater.”
Orchestration: Reflect-then-act planning; retrieve account history; call “CRM.findAccount,” then “Email.sendDraft”; ask one clarifying question if lead intent confidence <0.6.
Metrics: FPY ≥ 80% on drafts; assistance rate target 70%; hallucinations per 100 replies < 1.
Prompts: Canonical reply template enforcing tone and disclaimers; few-shots showing how to request clarification; adversarial samples (“Is this price still valid if I’m a student?”) to force policy adherence.
Tooling & about:blank#blocked-data- Tools: CRM.search, CRM.update, Email.sendDraft. Data contracts: lead.email, thread_id, account_id. Fallback: route to human with summarization if CRM latency > 3s.

Result: fewer “oops” emails, faster perceived response, and transparent reasoning in logs. The Prompt Spec made the experience tunable: on Fridays, lower Creativity and Agency to reduce risk during a skeleton crew.

Scenario 2: LedgerLens — AI reconciliation for finance ops

LedgerLens ingests bank statements and ERPs, flags mismatches, and proposes journal entries. The PRD listed screens and rules. It failed to capture the messy edge cases and the need for traceable reasoning a controller could audit.

Purpose: Identify and explain posting differences; never auto-post without a supporting citation and confidence >0.95.
Roles: “Matcher,” “Explainer,” “Policy Guard.”
Orchestration: Multi-pass: extract → match → justify. Call “ERP.fetchEntry,” “Bank.fetchTxn,” “Docs.retrievePolicy.” Require citations with paragraph IDs in every explanation.
Metrics: Review accept rate, average time-to-resolution, citation integrity score.
Prompts: Canonicals that force structured JSON with fields: hypothesized_match, support_evidence[], residual_risk. Negative shots demonstrating prohibited language (“probably,” “likely”) when confidence is insufficient.
Tooling & about:blank#blocked-data- RAG over accounting policies; function contracts for currency normalization; strict PII redaction policy.

With the Prompt Spec, every recommendation was reproducible. Auditors could inspect traces, see which policies were cited, and replay reasoning against the same versions. The team cut dispute resolution time by 40% without expanding UI scope.

Scenario 3: Scout QA — an agent that reviews pull requests

Scout QA reads diffs, catches risky changes, writes comments, and runs test plans. A PRD got lost in flags and filters. A Prompt Spec described how the agent reasons about code risk, when it runs tests, and how it escalates to a senior engineer.

Purpose: Highlight high-risk diffs and propose minimal, testable fixes; never auto-commit without a passing test artifact.
Roles: “Risk Analyzer,” “Test Planner,” “Patch Proposer,” “Safety Officer.”
Orchestration: Self-reflective loop: summarize diff → identify risk hotspots → propose tests → run unit tests via tool → update comments. Max 3 tool calls per file; escalate if test flakiness > 0.2.
Metrics: False positive rate < 15%; time saved per PR; merge-block precision.
Prompts: Schema-enforced review comments; few-shots including tricky patterns (e.g., concurrency issues, migrations touching PII).
Tooling & about:blank#blocked-data- Access to repo, test runner, and issue tracker; cost ceiling per PR; memory of past PR patterns.

Outcome: engineers trusted the agent. It didn’t try to be clever when confidence was low; it asked for help. That trust came from the Prompt Spec’s explicit risk posture and evaluation harness, not a vague “assistant” description.

Pattern library: reusable reasoning moves inside the spec

AI behavior is patternable. Your Prompt Spec should reference named reasoning and safety patterns the team understands, rather than reinventing them in prose every time.

Accordion Prompt: Start with a coarse plan; expand details only if ambiguity remains. Reduces token use and overthinking.
SER (Scaffold–Execute–Reflect): Plan the work, do the work, check the work. The default for any high-risk action.
Critic Pair: A second-pass “critic” role that only evaluates against schema, facts, and safety rules—no creativity allowed.
Checklist-Chain: Explicit checklist gating before tool calls; fails closed rather than guessing.
Fact Anchor: Every claim must point to a source or be marked as assumption with an ask-back. Slashes hallucinations.
Delta Diff: Instruct outputs as minimal diffs rather than full rewrites; improves editability and review.
Map–Reduce Summarize: Break large corpora into chunks with stable sub-summaries; recombine with dedup and contradiction checks.
Socratic Ladder: Ask a bounded set of clarifying questions in order of information gain, or escalate if none cross a threshold.

Encode these as toggles in the Prompt Spec. Don’t trust tribal memory. If you use SER, mandate that the reflect phase outputs a separate verification object with reasons and references, not just a confident tone.

Evaluation and governance: make behavior provable

A Prompt Spec is inseparable from its evaluation harness. If you can’t prove the behavior holds under real-world pressure, you don’t have a spec—you have an opinion. Bake evaluation into the artifact from day one.

Golden paths and red paths

Include both. Golden paths are canonical tasks the agent must ace—think top queries, top workflows, and noisy-but-common inputs. Red paths are landmines: adversarial prompts, policy-violating asks, and misleading data. Your CI should fail the build if red paths regress.

Goldens: 50–200 tasks covering 80% of usage.
Reds: 20–50 dangerous or off-distribution cases.
Fuzzers: Auto-generated variants that mimic real noise.

Metrics with teeth

Pick metrics that stakeholders care about. Tie them to business and risk. Your Prompt Spec should name the metric sources, sampling plans, and thresholds that block a release.

Cost per assisted task: Track model and tool spend, cap overruns.
Latency budget: P95 wall clock, with fallback policies.
Trace completeness: % of actions logged with inputs, outputs, and citations.
Safety incident rate: Violations per 10k requests.

Governance and versioning

Prompts change often. That’s not a bug; it’s the work. Version them like you version APIs. The Prompt Spec should declare version IDs for prompts, tools, and datasets, and specify a rollback plan for each. This enables safe, frequent releases.

Use feature flags and traffic splits to shadow-test new prompt versions against production traffic. Your spec declares the gating metrics and kill-switch conditions. No executive fiat; no guessing.

Shipping with Prompt Specs: the practical playbook

We ship fast using orchestrated AI agents and vibe coding—rapid, embodied prototyping with strong aesthetic and behavioral instincts. But vibes must converge into spec. Here’s how to move from idea to production using Prompt Specs.

1) Vibe first, spec second, code third

Start in a notebook or console. Converse with the model until you feel a crisp behavior. Name it. That’s your “behavioral gestalt.” Then write the Prompt Spec around what worked—not the other way around. Finally, instrument code to load and execute the spec.

2) Codify the dials and patterns

Declare Four Dial defaults and which patterns you’ll use (SER, Accordion, Critic Pair). This turns ambient decisions into auditable settings. Review these in design critique like you’d review API breaking changes.

3) Arrange the tool layer as contracts

Define tools as small, composable functions with strict schemas. In the Prompt Spec, tie tool preconditions, cost budgets, and error handling to behavior. Example: “Use ‘SearchInvoices’ only if invoice_count_estimate < 50; otherwise, call ‘QueryIndex’ with pagination.”

4) Build the evaluation harness on day one

Don’t wait for “later.” Put 20 goldens and 10 reds in the Prompt Spec before you wire UI. Have CI run them on every change and plot trend lines. Latency and cost budgets are part of the gate—not just correctness.

5) Observe behavior like SREs observe services

Traces, counters, histograms. The Prompt Spec should define event names and payloads for “plan_started,” “tool_called,” “reflect_failed,” and “escalated.” You can’t fix what you can’t see. Give operators live dials to tune behavior without redeploys.

6) Tighten the human-in-the-loop

When confidence is low or stakes are high, your agent must route to a human. The Prompt Spec defines how—to whom, with what context, and how to learn from the resolution. Handoffs aren’t a failure; they’re how you teach the system what “good” looks like.

Why Prompt Specs outperform PRDs in practice

Speed. You can iterate a Prompt Spec hourly, deploy behind a flag, and capture the impact in metrics. PRDs trap you in meetings about static UI when the real performance lies in reasoning quality and evaluation robustness.

Alignment. A Prompt Spec makes tradeoffs explicit: cost vs. quality, speed vs. safety. PRDs hide those inside vague “acceptance criteria.” With Prompt Specs, everyone sees the dials.

Resilience. Models change, tools break, data drifts. A Prompt Spec anticipates volatility by externalizing behavior. You can swap models or tweak patterns without unraveling the whole product.

Counter-arguments and hard edges

“We still need PRDs.” True, sometimes. Platform features, pricing pages, and deterministic subsystems benefit from PRDs. Use both. For the AI core, Prompt Specs are the source of truth. For supporting UI and infrastructure, PRDs can still define contracts and SLAs.

“Prompts are fragile.” They are—if you treat them like copy. Prompt Specs reduce fragility by adding structure: schemas, patterns, evaluations, and governance. You’ll still see drift when models update, but you’ll catch it in CI and roll back.

“Security and compliance teams won’t sign off on vibes.” Good. Give them Prompt Specs with data handling rules, PII masks, and auditable traces. Include red-team suites that probe abuse vectors. In our experience, this earns trust faster than a traditional requirements doc because it proves behavior under test.

“Metrics are noisy.” Yes. So pick few, meaningful ones and tie them to business outcomes. For example, measure assistance rate and downstream edits, not just BLEU-ish proxy scores. Noisy metrics beat no metrics.

“This seems heavyweight.” It’s lighter than a 20-page PRD, and far more actionable. A good Prompt Spec fits on 2–5 pages of structured content with links to goldens. It’s the minimum viable governance for models that can go off the rails.

Case studies: Prompt Specs in the wild

ParcelPilot: planning last-mile deliveries

ParcelPilot is a multi-agent planner that clusters orders, picks routes, and negotiates time windows with customers. Early on, the team used a PRD heavy on map UI and status states. The real leverage was in planning quality and how the agent handled conflicts—missing apartment numbers, gate codes, and weather events.

The Prompt Spec introduced two roles: “Planner” and “Negotiator,” with SER enforced. The Orchestration section allowed up to two rounds of customer outreach, limited to three clarifying questions to avoid harassment. The Tooling contract included a weather API and a traffic model, with Agency capped at two recomputations per route.

Metrics focused on on-time delivery rate, re-drive percentage, and customer satisfaction on rescheduling. A red-team suite attacked social engineering (“I live next door, can you leave it with me?”). The result: 12% fewer missed deliveries and a 20% reduction in dispatcher escalations. The UI remained minimal; the intelligence carried the product.

NovaCare Intake: triaging healthcare appointments

NovaCare built an intake agent to route patients to the right provider. The PRD listed dozens of forms and branching paths. The Prompt Spec defined roles (“Intake Nurse,” “Policy Guard”), a Fact Anchor pattern requiring citations from insurance policy docs, and a Socratic Ladder to ask at most four high-yield questions before escalation.

Goldens included common, vague complaints; reds included tasks that might trigger emergency escalation (chest pain patterns). The safety posture was conservative: the agent always surfaced “seek immediate care” in specific symptom clusters. The result: a measurable drop in misroutes and a compliance sign-off because auditors could replay decisions with sources.

Fintrace Analyst: pre-underwriting risk summaries

Fintrace ingests business docs and bank statements to produce pre-underwriting memos. The Prompt Spec mandated a Citation Integrity score: every financial claim had to tie to a page and line number from the source, with a “residual risk” field. Four Dials defaulted to low Creativity, high Fidelity, medium Agency, and shallow Memory.

The spec allowed debate between “Extractor” and “Analyst” roles for complex cases. Evals included adversarial documents with mislabeled tables and OCR artifacts. With that, Fintrace improved memo acceptance from 62% to 88% and cut review time in half. The PRD never would have captured that behavior.

From artifact to platform: Prompt Specs as code

Don’t bury Prompt Specs in wikis. Treat them like code. Store in repo, version with semver, review via pull requests. The spec should be the single source of truth for deployment configs, evaluation suites, and monitoring dashboards.

Spec-as-config: Your runtime loads prompts, tool contracts, dials, and evals directly from the spec.
PR reviews: Changes to canonicals or patterns require sign-off from Prompt Architects and Risk Owners.
CI gates: Run goldens/reds, smoke tests, and cost/latency checks on every change.
Dashboards: Auto-generate operational dashboards from declared metrics.

This collapses the hallway between “product” and “engineering.” Everyone works on the same artifact. Changes are trackable, testable, and reversible.

Team roles and rituals for Prompt Specs

AI-native studios need new hats and sharper rituals. The Prompt Spec clarifies ownership and accelerates healthy debates.

Prompt Architect: Owns canonicals, patterns, and Four Dial defaults; ensures internal coherence.
Behavioral QA: Designs goldens/reds, maintains test integrity, and hunts regressions.
Toolsmith: Owns tool contracts, schemas, and performance; keeps costs predictable.
Data Librarian: Curates retrieval corpora, sources, and safety filters.
Risk Owner: Signs off on safety rails, escalation policies, and compliance posture.

Rituals change too:

Spec Reviews: Short, frequent reviews focused on behavior and metrics, not slideware.
Trace Reads: Weekly sessions reading model traces to spot pattern anti-patterns.
Red Team Days: Intentional breakage to validate rails and drills for incident response.
Dial Drills: Tabletop exercises where you simulate cost spikes or model regressions and adjust dials live.

Common anti-patterns to avoid

Don’t bury critical constraints in prose. If a rule matters, enforce it via schemas, patterns, and evals. Humans skip paragraphs; machines honor contracts.

Avoid “mega prompts” that try to do everything. Break behavior into roles and stages. Use Orchestration to decide who does what and when. This improves debuggability and performance.

Don’t attach evals as an afterthought. If a behavior doesn’t have a golden and a red, assume it will regress. Similarly, avoid wordy “style guides” without examples. Few-shot beats philosophy.

What goes into a high-quality Prompt Spec

Here’s a template we use often. It fits on a couple of pages but holds the core behaviors.

Header: Name, owner, version, risk class, last updated.
Purpose: Objective, out-of-scope, red lines.
Four Dials: Default settings and permitted overrides.
Roles: Definitions, transitions, and escalation policy.
Orchestration: Planning mode, tool call policy, memory policy.
Prompts: Canonical system/developer messages, few-shots, adversarials.
Schemas: Output shapes with examples, validation rules.
Tools: Contracts, costs, latency expectations, error handling.
about:blank#blocked-data- Retrieval sources, freshness, PII handling, redaction.
Evaluation: Goldens, reds, fuzzers, metrics, gating thresholds.
Observability: Event names, trace schema, dashboards.
Change log: Notable changes and their impact on metrics.
Rollback plan: Conditions and steps to revert to prior versions.

Integration with orchestration frameworks

Whether you use LangGraph, Assistants, or your own runtime, the Prompt Spec should be your orchestration input, not scattered code. Map roles to nodes, patterns to control loops, and tools to function registries. Keep the behavior portable by avoiding vendor-specific prompt magic unless you can simulate it in tests.

For multi-agent systems, declare inter-agent contracts. Example: “Planner outputs tasks with resource tags; Executor accepts only tasks with resolved dependencies; Critic evaluates outputs against acceptance tests.” Your spec should describe their shared schemas and escalation routes.

Costs, latency, and model churn

AI-native products live under cost and latency constraints that PRDs rarely capture well. The Prompt Spec does. Declare budgets up front, plus fallback strategies. If cost spikes or models degrade, you know which dial to turn and what to drop gracefully.

Cost budgets: Max dollars per task, with breakdown across tools.
Latency budgets: P50/P95 targets and timeouts; define spinner vs. email callbacks.
Model policy: Supported model versions, upgrade cadence, and canary routes.

When a model update lands, run your evals. If goldens slip or reds loosen, hold the upgrade or adjust patterns. Prompt Specs make upgrades disciplined, not chaotic.

Legal, safety, and enterprise readiness

Enterprise buyers want proof of control. The Prompt Spec is a gift to legal and security teams: it shows what the agent will and won’t do, how it treats data, and how it fails safely. Include a compliance addendum with data flows and retention policies.

Safety is not moralizing; it’s engineering. Your spec should convert policies into machine-checkable rules. Example: “If user requests medical diagnosis, respond with triage guidance and direct to licensed care; include disclaimer X; log incident tag ‘policy_medical_advice.’” That’s enforceable and auditable.

Design and UX through the lens of Prompt Specs

Good model behavior reduces UI weight. But you still need to communicate uncertainty, ask good questions, and show provenance. The Prompt Spec should include UX guidelines that bind to model outputs.

Uncertainty UI: Visualize confidence and residual risk without numbers the user can misinterpret.
Ask-back patterns: Pre-approved question stems that fit brand voice.
Provenance: Inline citations, expandable evidence panels, and “why this suggestion” notes.
Escalation affordances: Clear handoff buttons and response SLAs.

Tie these to schema fields (e.g., “assumptions[],” “citations[],” “residual_risk”). Designers and engineers stop arguing about style because the data structure drives the UI.

Prompt Spec maturity levels

Not every team needs maximal structure on day one. Use maturity levels to scale up discipline as your risk grows.

Level 1 – Prototype: Basic Purpose, Canonical prompt, a handful of goldens/reds. Single role. Manual review.
Level 2 – Beta: Four Dials, SER pattern, 50+ goldens/reds, cost/latency budgets, simple observability.
Level 3 – GA: Multi-role orchestration, full schemas, tool contracts, enterprise safety rails, CI/CD with gates.
Level 4 – Regulated: Audit-ready traces, policy-driven retrieval, sign-offs, data retention and deletion policies.

Declare your target level in the spec header. This aligns stakeholders on what “done” means.

Migration: converting a PRD into a Prompt Spec

You don’t need to scrap months of PRD work. Translate it. Extract user goals into Purpose. Convert acceptance criteria into goldens. Map error states into reds. Identify backend APIs as Tools with contracts, not just endpoints.

Replace “shall” statements with schemas and patterns. “The system shall provide helpful explanations” becomes “Output ‘explanation’ field with 2–4 sentences, each with a citation ID; Critic Pair rejects missing citations.” The PRD becomes inputs; the Prompt Spec becomes the operating system of behavior.

How to apply this tomorrow

You can ship a v1 Prompt Spec in a day. Here’s a concrete plan that works for startups and teams inside big companies.

Step 1: Pick one workflow and write a Purpose page

Define Objective, Out-of-scope, and Risk posture in three bullets each.
Set Four Dials defaults. Pick one pattern: SER.
Nominate a Prompt Architect and a Risk Owner.

Step 2: Draft the minimal canonicals and schemas

Write a tight system prompt (≤ 20 lines) that encodes Purpose and role.
Create one developer message defining output JSON with fields needed by UI.
Add two few-shots: one happy path, one tricky edge.

Step 3: Add three tools with clear contracts

List names, args, returns, and expected latencies.
Define when to call each tool and what to do on failure.
Cap max tool calls per request.

Step 4: Build the first eval harness

Write 20 goldens and 10 reds sourced from real data.
Define gating metrics: FPY target and hallucination max.
Wire these to run in CI on every prompt change.

Step 5: Observe and iterate

Instrument traces with plan/actions/reflections.
Hold a 30-minute Trace Read daily for the first week.
Update canonicals and few-shots, noting changes in the change log.

Step 6: Expose dials to operations

Add a simple admin panel to tune Creativity and Agency.
Define safe ranges in the Prompt Spec.
Run a Dial Drill: simulate a cost spike and adjust live.

In a week, you’ll have a living artifact, shipping behavior, and a team speaking the same language. That beats a deck everyone pretends to have read.

Bottom line

AI-native products demand a new artifact. Prompt Specs replace vague requirements with executable behavior, embedded evaluation, and operational dials you can actually turn. If you want to ship fast and stay in control, stop writing PRDs for agents—spec their minds instead.