If you've built products with AI agents — or you're about to — you've already felt the problem. You describe what you want. The agent builds something close but wrong. You describe it again, differently. Closer. Still wrong.
The gap isn't the AI. The gap is what you gave it.
Intent engineering is the discipline of making product judgment explicit: what to build, for whom, and on what evidence. An AI agent then acts on reviewable decisions instead of guessing.
What Is an Intent?
An intent is a single user problem worth solving, with explicit outcomes and reasoning. Evidence can support that reasoning; when it is missing, keep the assumptions visible.
It's not a feature request. It's not a Jira ticket. It's not a user story. Here's how they differ:
| Artifact | Example | Problem |
|---|---|---|
| Feature request | "Add dark mode" | No evidence it matters, no success criteria |
| Jira ticket | "Implement dark mode toggle in Settings" | Prescribes the solution, not the problem |
| User story | "As a user, I want dark mode so I can reduce eye strain" | Points at the problem but isn't testable or traceable |
| Intent | Reduce eye strain during extended evening sessions — evidenced by 7 friction reports and NPS comments citing screen brightness | Problem-rooted, evidence-backed, outcome-oriented |
An intent starts with what users are experiencing and ends with what will be true when the problem is solved. It doesn't specify buttons, endpoints, or architecture.
What Is an Intent Spec?
An intent spec is the structured document that makes an intent executable. It contains:
| Component | What it answers |
|---|---|
| Objective | What user problem are we solving and why? |
| Outcomes | What observable state changes happen? |
| Evidence | What signals support or challenge the claims, when available? |
| 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? |
That's it. Half a page. No "Background" section, no implementation notes, no 12-page PRD.
The intent spec is short because it's precise. Every line is testable. If an outcome says "User can export a report in under 5 seconds," you can verify that. If a PRD says "Improve the export experience," you can argue about it forever.
For the full breakdown of each component, see The 8-Part IntentSpec.
Why "Engineering"?
Because this is a precision discipline, not a writing exercise.
Engineering implies:
- Structure over prose. An intent spec has a defined shape. You don't get to freelance the format.
- Evidence over opinion. Claims trace back to user evidence: friction, quotes, observations, metrics, requests. An intent without evidence is an assumption, labeled as one.
- Testability. If you can't verify an outcome, it doesn't belong in the spec. "Improve onboarding" is not an outcome. "New users complete setup in under 2 minutes" is.
- Traceability. From user pain to evidence to intent to shipped code. Every link in the chain is explicit and auditable.
The word "engineering" is deliberate. You don't write intents. You engineer them.
How It Fits Together
The loop has four steps:
Evidence → Capture real user signals (friction, quotes, observations, metrics, requests). Each one lands unreviewed until a person judges it. Evidence is optional, but a claim without it stays visible as an assumption. See the discovery play.
Proposal → The coding agent proposes an intent.md from the request and the repo: objective, outcomes, constraints, edge cases, verification, and the open product choices it can't settle alone.
Judgment → The product manager reviews it in Pathmode, answers the open choices, requests corrections, and authorizes the exact revision.
Build → The agent builds only that authorized revision. The merge marks it shipped, and the outcomes are measured afterward.
The repo gets the decision. Pathmode keeps the evidence and judgment behind it. For the full walkthrough, see Your First Intent in Pathmode.
What Intent Engineering Replaces
It doesn't replace your product process. It replaces the artifacts your process produces:
| Before | After |
|---|---|
| PRDs that nobody reads past page 2 | Intent specs that fit on one screen |
| Feature backlogs ranked by gut feel | Priorities your team sets by weighing the evidence behind each intent |
| "Definition of done" debates | Verification criteria written into the spec |
| Vague Jira tickets that agents misinterpret | Authorized specs that give agents explicit, reviewable judgment to act on |
| Anecdotal user feedback in spreadsheets | Typed evidence on a searchable board |
You still talk to users. You still prioritize. You still make judgment calls. But the output of that work is now precise, testable, and executable — by humans or AI agents.
Where Intent Engineering Sits
Three layers get conflated — pull them apart:
- Intent — the Why: what to build, for whom, on what evidence. This is product judgment. (Pathmode)
- Implementation — the How: the technical contract — architecture, types, tests. (code-spec tools)
- Tasks — the When: status, assignees, sprints. (Jira, Linear)
Most tools live in How and When. Why — the judgment about whether you're building the right thing at all — is the layer that's been missing. Pathmode is the product judgment layer.
Context isn't judgment. You can hand an agent every file in your repo and it still won't know which trade-off you'd make.
Where to Go Next
- Learn the spec format: The 8-Part IntentSpec — the components every spec must contain.
- See a worked example: From Support Ticket to Shipped Feature — a complete end-to-end walkthrough.
- Start capturing evidence: From User Interview to Reviewed Evidence turns your conversations into structured input you can review.