Why Jira Tickets Fail AI Agents

You gave your AI agent access to Jira. It read every ticket, understood every subtask, and followed the acceptance criteria word for word.

The diff was clean. The tests passed. It still built the wrong thing.

A weak ticket does not confuse an AI coding agent. It gives the agent freedom. The agent chooses a plausible interpretation, writes code that satisfies the words, and returns a result that looks finished. That is what makes the failure dangerous.

Anatomy of a Jira Ticket

Consider this illustrative ticket:

Title: Improve checkout UX
Description: Users are dropping off at checkout. Make it faster.
Acceptance Criteria:
  - Checkout completes in under 3 seconds
  - Show a loading indicator during payment processing
  - Handle payment errors gracefully

A reasonable coding agent can satisfy every line. It trims a slow request, adds a spinner, wraps the payment call in a try/catch, and shows "Something went wrong" when the provider fails.

The ticket passes. The user problem may not.

Perhaps shoppers leave because they cannot tell whether a retry will charge them twice. Perhaps an embedded payment widget fails only on iOS Safari. Perhaps the order summary disappears at the moment trust matters most. Nothing in the ticket tells the agent which interpretation is true, what it must preserve, or how to prove that the change helped.

A human engineer sees those omissions and asks the product manager. An agent sees three acceptance criteria and starts implementing.

The Four Gaps

The problem is not that Jira cannot hold richer information. It can. The problem is that most tickets are written to coordinate humans, who fill gaps through conversation. When the ticket becomes the agent's complete implementation authority, those gaps become permission to guess.

The Context Gap. Why are shoppers dropping off? Speed, confusion, trust, an inaccessible payment widget, or a broken coupon field could produce the same funnel shape. Without the current failure and the evidence behind it, the agent optimizes the first plausible cause.

The Intent Gap. "Improve checkout UX" is a direction, not a destination. The agent needs an objective that names the problem and why it matters, followed by observable outcomes that describe the state after success.

The Constraint Gap. What must the implementation never violate? A retry must not create a second charge. The payment provider and PCI boundary may need to remain intact. These are hard boundaries, not preferences the agent can trade away.

The Verification Gap. "Handle errors gracefully" is a judgment, not a runnable check. Without a concrete feedback loop, a generic error message can look complete. The spec needs to say which automated, manual, and shipped signals would establish that the behavior changed.

These gaps are not bugs in Jira. A ticket is usually a shared reminder to have a conversation. But when an agent reads it, the reminder is treated as the result of that conversation.

What Preflight Makes Visible

Copying the ticket into a file does not repair it. If the example above were promoted mechanically into an intent.md, a readiness check could produce:

readiness: "failed 3/6 — blocking: constraints, edge-cases, verification"

Pathmode's preflight checks six dimensions: a focused title, a specific objective, observable outcomes, a hard constraint, an edge case with defined behavior, and concrete verification. It is deterministic, so an unchanged file receives the same verdict every time.

The verdict does not decide whether "make it faster" is the correct product judgment. No lexical check can prove that speed caused the drop-off. It makes missing decisions visible, distinguishes absent text from a substantive claim the check could not confirm, and keeps that state in the file the next agent reads. The First Artifact Has No Readiness Gate explains how that mechanism works and where human judgment still belongs.

The Artifact the Agent Actually Needs

Once the team resolves the missing decisions, the same handoff can become an agent-ready intent.md:

---
id: "checkout-payment-timeout"
version: 1
status: "draft"
readiness: "passed 6/6"
scope:
  inScope:
    - PaymentStep status and retry behavior
    - Payment status and retry API endpoints
  outOfScope:
    - Replacing the payment-provider widget
    - Redesigning earlier checkout steps
---
# Fix checkout payment timeout recovery

## Objective
Shoppers abandon checkout when payment processing stalls without status or a
safe recovery path. Those abandoned attempts reduce completed orders.

## Outcomes
- Payment status appears within one second of submission
- 95% of payment attempts reach success, failure, or pending within three seconds
- Shoppers with a recoverable failure can retry without re-entering order details

## Constraints
- A retry must never create a second charge for the same payment attempt
- The existing provider widget and PCI boundary must remain unchanged

## Edge Cases
- **Provider times out after receiving the charge request**: Keep the order pending
  and reconcile provider status before enabling retry
- **The shopper loses their network connection**: Restore the last known payment
  status without submitting the charge again

## Health Metrics
- Checkout completion outside the payment step does not decrease

## Verification
- Automated check: simulate a provider timeout and confirm retry reuses the same
  idempotency key
- Automated check: under a throttled connection, status appears within one second
  and retry appears only for recoverable failures
- Shipped signal: compare payment-step abandonment with the pre-change baseline
  after two full weeks

The objective explains the problem. Outcomes define observable success. Constraints and scope bound the agent's freedom. Edge cases say what should happen when the happy path breaks. Verification gives the agent, CI, and the product team feedback at different stages.

It still does not prescribe the implementation. The coding agent decides how to change the code inside those boundaries.

Jira Still Tracks the Work

The answer is not to replace Jira with a longer document inside another tool.

Jira remains useful for ownership, sequencing, dependencies, status, and the rest of the coordination around delivery. The product decision lives in the repository, where the coding agent already reads and where the reasoning can change with the code. The Jira issue links to that decision instead of trying to duplicate it in a description and a comment thread.

That is the split: Jira tracks when and by whom the work moves. intent.md defines why the change matters, what success looks like, and which boundaries the implementation must respect. See how Pathmode and Jira fit together, or read why the repo gets the decision.

Your agent is not broken. Jira is not broken. The handoff is incomplete.

A ticket is a reminder to talk to someone. A spec is the result of having talked. That is intent engineering.