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. Five parts have to be there first: the Objective the work serves, the Evidence behind it, the Outcomes to protect, the Edge cases that break it, 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 five 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.
- 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.
- Outcomes — what must be true when this is done. The result to protect, stated as a user-visible change. Without it, the agent ships features and misses the point — the failure mode above.
- 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.
- Verification — how anyone proves it worked. The fastest check, the manual fallback, and what must not regress. 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. Evidence justifies the Objective; the Objective sets the Outcomes; the Outcomes expose the Edge cases; Verification proves the Outcomes survived. Skip a step 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 five parts gets skipped most?
- The Objective and the Outcomes. Most specs jump straight to features because features feel concrete. But an agent that knows what to build but not what to protect will ship the features and miss the point — which is exactly how correct code becomes the wrong thing.
- 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 what must not regress turns the outcome into something the agent and the reviewer can both test against, not argue about after merge.