Pathmode authors a spec into an IntentSpec from real customer evidence before engineering starts, so the build serves the decision you made, not just a feature list. Eight parts have to be there first: the Objective the work serves, the Outcomes to protect, the Evidence behind them, the Constraints the agent can't cross, the Scope it may and may not touch, the Edge cases that break it, the Health Metrics that must not degrade, and the Verification that proves it worked.
A spec landed in the queue with a tidy bullet list: add filters, add a saved-views menu, add a CSV export. The agent built all three, clean and tested. Nobody noticed until a user said it out loud — they didn't need more ways to slice the table, they needed the one report they pulled every Monday to send itself. The spec described features. It never named the outcome those features were supposed to produce, so the agent optimized the list and missed the job.
What was missing wasn't detail — it was judgment
The feature list was specific. It just answered the wrong question. A spec full of what to build with no what this is for hands the agent a target it can hit perfectly and still be wrong. Detail without intent is just a longer way to be precise about the wrong thing.
A spec isn't a description of the work — it's the judgment the work has to honor.
The eight parts that have to be there before an agent starts
Run the spec against this checklist. If any line is missing, the agent is guessing about something you already decided.
- Objective — the decision the work serves. One sentence naming what changes for the user and why now. Without it, the agent optimizes the feature list instead of the goal behind it.
- Outcomes — what must be true when this is done. The result to protect, stated as a user-visible change, not a task. Without it, the agent ships features and misses the point — the failure mode above.
- Evidence — the signals that motivated the work. The tickets, quotes, and friction that made this worth doing. Without it, the agent can't tell a load-bearing requirement from an offhand preference.
- Constraints — what the agent must not do. The hard lines: security rules, business invariants, architectural decisions it can't violate. Without them, you get technically correct code that breaks a rule no one wrote down.
- Scope — what it may touch, and what it must leave alone. The change surface, drawn as a fence. Without it, a focused fix becomes a 40-file diff that "improved" code you never asked about.
- Edge cases — where the happy path breaks. The empty state, the conflicting input, the abusive case. Without them, the agent assumes the inputs are clean and you find out in production that they weren't.
- Health Metrics — what must not degrade. The things that have to stay true after the change — load time, completion rate, the flows already working. Without them, the agent optimizes the new outcome and quietly wrecks something it was never told to protect.
- Verification — how anyone proves it worked. The fastest check, the manual fallback, and the shipped signal that confirms the outcome held. Without it, "done" is an opinion and the spec can't close the loop.
Why this is the order, not just the list
The parts build on each other. The Objective leads because everything under it serves a decision; the Outcomes make that decision testable; the Evidence is the proof that earns both the right to exist. Constraints and Scope fence in how the agent is allowed to reach the outcomes — what it can't do, and what it can't touch. Edge cases catch where those outcomes break, and Health Metrics name what the agent could wreck while chasing them. Verification closes the loop: proof the outcomes held and nothing on the Health list moved. Skip a part and the ones after it are guesses. A spec that runs the full sequence is one an agent can act on without filling the gaps with its own assumptions — and the gaps are exactly where it goes wrong. For a field-by-field walkthrough, see the anatomy of an agent-ready spec.
Frequently asked questions
- Which of the eight parts gets skipped most?
- Scope and Health Metrics — the two that fence the agent in. Teams name what to build, and often what success looks like, but rarely what the agent must not touch or what it must not break getting there. Leave those out and a technically correct feature still lands as a sprawling diff that quietly regressed something you cared about. Correct code, wrong result.
- Where does the Evidence come from?
- From signals you already have — support tickets, user interviews, observed friction, metrics. Pathmode assembles that into the spec so the reason for the work travels with it, instead of staying in the head of whoever wrote the ticket.
- Isn't Verification an engineering concern, not a spec concern?
- Verification belongs in the spec because it defines done before the work starts. Naming the fastest check, the manual fallback, and the shipped signal that confirms the outcome held turns it into something the agent and the reviewer can both test against, not argue about after merge.