How to Write an AI Spec: The Document That Decides Whether AI Works

The difference between an AI demo and an AI system is usually a document. Demos are built from a prompt and an idea; systems are built from a specification that says what the system is for, what correct means, how much it may do on its own, what it does when unsure, and how it will be judged. This guide provides the sections and how to write each, drawing on FISTA Solutions' AI enablement practice. The delivery method built around the spec is in the spec-driven development whitepaper and the criteria section in depth in how to write acceptance criteria for ai.

What sections does the spec contain?

Section	Content	Owner
Purpose and workflow	The process, its baseline, and what the system changes	Product owner
Users and roles	Who uses it, who reviews, who is affected	Product owner
Scope and exclusions	Categories in and out; systems read and written	Product owner
Correctness	What correct means per category, with examples and edge cases	Domain experts
Acceptance criteria	Thresholds, datasets, methods, sign-off	Product and evaluation
Autonomy and gates	Level per action; approval points; budgets	Product, risk
Failure behavior	Low confidence, missing data, tool errors, refusals	Product, engineering
Data	Sources, permissions, quality, lineage, residency	Data owner
Integration	Systems, tool contracts, permissions, idempotency	Engineering
Budgets	Latency, cost per task, volume assumptions	Engineering, finance
Risks and controls	Register with owners	Risk
Success metrics	KPIs and reporting cadence after launch	Product
Open questions	What discovery must resolve	All

How do you write the correctness section?

With domain experts, on real cases: for each category, what a correct output is, what an acceptable variation is, what an error is, and what must never happen, illustrated with labeled examples that seed the golden dataset. This section is the most often missing and the one that determines whether evaluation can exist. Dataset construction is in what is a golden dataset and the discovery sessions that produce it in how to run ai discovery.

How do you specify autonomy and gates?

Per action, not per system: which actions the system may take independently within limits, which require approval, and which it may only suggest, with the consequence and reversibility reasoning recorded. Gates are specified as tool-layer controls with approver roles and timeouts. Autonomy graduates on evidence, and the spec records the current map. The scale is in what is an autonomy level in ai and gate design in what is a human approval gate.

How do you specify failure behavior?

For each failure mode, what the user sees and what the system does: low confidence routes to review with the evidence attached; missing data prompts for it or escalates; tool errors retry within limits then hand off; out-of-scope requests are refused with a clear message; and adversarial inputs are detected and logged. Failure behavior is tested by cases in the golden dataset. Guardrail implementation is in ai agent guardrails.

How do you handle data and integration?

As verified facts: each data source with access confirmed, permissions understood, quality assessed on the fields needed, and residency constraints recorded; each integration with API access tested, tool contracts drafted, permission scoping decided, and idempotency requirements stated. Assumptions here are where funded projects stall. Readiness practice is in the ai data readiness checklist and tool contracts in how to build tool use for llm agents.

How do you set budgets, risks, and metrics?

Budgets: latency targets per interaction type, cost per task at expected volume, and the routing and caching assumptions behind them. Risks: a register with likelihood, impact, control, and owner. Metrics: the KPIs by which the system will be judged after launch and the reporting cadence. Each links the spec to the business case and the governance review. Register format is in ai risk register and KPI design in how to set ai kpis.

Who writes it and how detailed should it be?

The product owner leads; domain experts own correctness; engineering owns integration, budgets, and feasibility informed by discovery evaluation; risk sets tier requirements; the sponsor approves. Detail is sufficient when an engineer can build without guessing, an evaluation engineer can test, and an auditor can check. Correctness, thresholds, gates, and failure behavior need precision; implementation choices can stay open. The product role is in hire technical product managers.

How does the spec evolve?

It is versioned. Discovery refines scope and thresholds from evaluation; the pilot refines failure behavior and gates from real cases; production refines budgets and metrics from actuals. Every change records its reason, and the current version is the release gate for every prompt, model, or tool change. A spec frozen at approval is as wrong as no spec.

What mistakes produce demos instead of systems?

Specs that describe features without correctness; one aggregate accuracy target; autonomy left to the model; failure behavior unspecified; data and integration assumed; budgets absent so cost surprises arrive with adoption; and specs written by engineering alone or by product alone. Each is visible in the document before a line of code exists.

How FISTA Solutions writes AI specs

FISTA Solutions writes specifications during discovery with client product owners, domain experts, and risk functions, seeds golden datasets from the correctness section, verifies data and integration before sign-off, and keeps the spec versioned as the release gate through delivery and operation. The AI enablement practice leads specification, forward deployed engineers build to it, and AI agents ship gated by it. The record behind the approach is 150+ projects with 99.9% uptime.

To write the document that decides whether your AI system works, message FISTA on WhatsApp, or read the spec-driven development whitepaper for the method around it.