An IntentSpec isn't mainly a document to read. It's product judgment in structured form. Whether you express it in JSON, YAML, or structured English, a spec has these 8 parts. The preflight checks six gates: a title plus five of the parts (objective, outcomes, constraints, edge cases, and verification). Evidence, Scope, and Health Metrics are not gated, but they tell the agent where the claims come from, what it may touch, and what must not degrade.
Objective (The "Why" & "What")
What: The problem to solve and why it matters. Why: Gives agents the necessary context to make trade-offs when implementation details get tricky.
"objective": "Reduce cart abandonment caused by payment step timeouts exceeding 3 seconds."Outcomes (The Observable State changes)
What: The observable, testable state changes after success. Why: Defines the true "Definition of Done". These aren't tasks, but user-visible states.
"outcomes": [
"Payment completes in under 3s (p95)",
"Users see real-time status during processing",
"Failed payments show actionable error with retry"
]Evidence (The Proof)
What: Linked real user signals (friction points, quotes, metrics). Why: Eliminates solutioneering. A claim you can't link to user evidence is an assumption, and it should be visible as one. In Pathmode, evidence is anchored to the claim it backs, and a claim with none reads "No evidence."
"evidenceIds": ["evd-101", "evd-102"],
"evidenceAnchors": {
"objective": ["evd-101"]
}Constraints (The Guardrails)
What: Hard boundaries—what the agent CANNOT do. Why: Critical for security, architectural integrity, and business rules. (When a constraint holds for every feature, promote it to The Product Constitution instead of retyping it per spec.)
"constraints": [
"No double-charge on retry",
"Must support iOS Safari 15+"
]Scope (What to Touch — and What Not To)
What: The parts of the system the agent may change — and the parts it must leave alone. Why: Keeps the change surgical. "Out of scope" is a fence that stops the agent from refactoring code you never asked it to touch.
"scope": {
"inScope": ["The payment retry path and its error states"],
"outOfScope": ["Cart UI", "Tax calculation", "Saved payment methods"]
}Edge Cases (The Boundaries)
What: Failure modes and boundary conditions. Why: Happy paths are easy. Agents need to know how to handle the 1% of cases where things go wrong.
"edgeCases": [
{
"scenario": "Network timeout during payment",
"expectedBehavior": "Show retry button, no double-charge"
}
]Health Metrics (What Must Not Degrade)
What: What must stay true after the change — the regression guards. Why: Outcomes say what should change; health metrics say what must NOT. Agents optimize for the outcome — name what they could quietly break getting there.
"healthMetrics": [
"Checkout completion rate does not drop",
"Payment page p95 load time stays under 2s"
]Verification (The Tests)
What: Concrete tests to confirm success. Why: Don't just let the agent say "done". Force it to prove success code-first.
"verification": {
"checks": [
{ "kind": "fastest", "description": "Force a payment timeout in staging: the retry button appears and no second charge posts", "status": "unknown" },
{ "kind": "test", "description": "Run checkout-payment-retry.spec.ts and confirm the retry path passes", "status": "unknown" },
{ "kind": "shipped-signal", "description": "Abandonment at the payment step drops in the two weeks after release", "status": "unknown" }
]
}The Cheat Sheet
| Component | Question it Answers |
|---|---|
| Objective | Why are we building this? |
| Outcomes | What observable state changes happen? |
| Evidence | What user signals prove this is needed? |
| Constraints | What must we NOT do? |
| Scope | What should the agent touch — and leave alone? |
| Edge Cases | What happens when it breaks? |
| Health Metrics | What must NOT degrade? |
| Verification | How do we prove it works? |
Print this out. Tape it to your monitor. Or better yet — make sure your tooling enforces it.