Why Traditional Tickets Fail for AI Agents

An agent received a human-style user story: "Add JWT authentication to the API." No file paths. No type signatures. No reference to existing code.

The agent hallucinated file paths that didn't exist, invented API signatures incompatible with the codebase, and created types that duplicated ones already defined three directories away. The code compiled. It was wrong in every way that mattered.

Every ticket now carries explicit implementation instructions: filesToCreate lists exact paths for new files. filesToModify names every existing file the agent will touch. codeReferences provides the actual signatures and patterns the agent must follow. typeReferences defines the TypeScript types the agent must use — not invent.

Multiple agents working in parallel modified the same file. Agent A added an import at line 3. Agent B rewrote the function starting at line 5. Agent C added a new export at the end.

Three-way merge conflicts on every file touched by more than one agent. Manual resolution wiped out the productivity gains of parallel execution. The more agents ran simultaneously, the worse it got.

With filesToCreate and filesToModify declared in the schema, a scheduler can compute which tickets touch which files before execution starts. Tickets that share files go into the same wave — sequential within the wave, parallel across waves. Zero file collisions by construction, not by luck.

The ticket lifecycle had an explicit "blocked" status. When a dependency wasn't met, the ticket was marked blocked. When the dependency resolved, someone (or something) had to remember to flip it back to "ready."

Agents got stuck in blocked state because nothing triggered the transition back. Tickets that were theoretically unblocked stayed frozen. The blocked status created a dead state that required external intervention to escape — the opposite of autonomous execution.

Blocked was eliminated as a status. The lifecycle became four clean states: pending → ready → active → done. Blocked is now inferred from the dependency graph: if a ticket's dependencies (type: blocks) aren't done, it's pending. When they resolve, it becomes ready automatically. No status transition needed. The dependencies.type field distinguishes blocks (hard gate — cannot start) from requires (needs output, but can be sequenced flexibly).

With dozens of agents executing tickets in parallel, each one produced code in its own style. Different naming conventions. Different error handling patterns. Different import orderings. Different return type shapes.

The codebase compiled but looked like it was written by 50 different people — because it was. Consistency reviews became the bottleneck. The more agents you added, the worse the Frankenstein effect got.

Patterns became a first-class entity in the schema, defined at the Specification level and inherited by every Epic and Ticket beneath it. codeStandards encodes naming conventions, error handling strategy, and language-specific rules. commonImports lists the import statements every ticket should use. returnTypes defines the standard response shapes (e.g., Result<T, E> patterns). Define once at the top. Every agent reads the same patterns.

Architecture diagrams, ADRs (Architecture Decision Records), and mockups lived in separate documents — Notion pages, Confluence wikis, Figma files, scattered markdown. No agent knew they existed.

Agents reimplemented things that had already been decided differently. ERD diagrams showed a normalized schema; the agent created a denormalized one. An ADR specified event-driven communication; the agent built synchronous REST calls. Design decisions existed but had no path to execution.

Blueprints became a first-class entity in the schema, directly linked to a Specification. Each blueprint has a typed category (flowchart, architecture, sequence, erd, adr, mockup, component, deployment, api), a format (mermaid, markdown, ascii, mixed), a lifecycle status (draft, review, approved, deprecated), and the actual content inline. The agent doesn't need to search for design documents — they're in the same payload as the tickets.

Tickets without explicit acceptance criteria produced code that "worked" in isolation but didn't satisfy the actual requirement. The agent declared the ticket done because it had no way to verify otherwise.

Reviews became the only quality gate. But by the time a human reviewed the output, the agent had already moved on, building subsequent tickets on top of incorrect foundations. Errors compounded geometrically.

acceptanceCriteria became a required array of verifiable strings on every ticket. Combined with testSpecification.gates (unit, integration, e2e), it creates a binary contract: either the ticket passes all criteria and all gates, or it's not done. No ambiguity. No "it mostly works." The agent has a checklist it can verify before declaring completion.

Without tracking estimated vs. actual time, there was no signal to calibrate decomposition quality. Tickets estimated at 2 hours that took 20 were indistinguishable from tickets that took 2.

Decomposition quality stagnated. The system produced tickets that were either too granular (wasting orchestration overhead) or too broad (exceeding context windows and agent capabilities). There was no feedback mechanism to improve.

Both estimatedHours and actualHours live on every ticket. The delta between them is the decomposition quality signal. If actual consistently exceeds estimated, the tickets aren't atomic enough — the decomposer needs to produce smaller units. If actual is consistently a fraction of estimated, tickets are over-decomposed. The schema carries the evidence that the next decomposition cycle needs to improve.

In long conversations, the model compacts context. Critical information — which file to create, which type to reference, which pattern to follow — silently disappears from the window. The agent keeps executing, but it's now operating on incomplete information.

The agent produces plausible but wrong output. It invents what it can't remember. And because the output looks correct — syntactically valid, structurally reasonable — the error isn't caught until integration, when the damage is already done.

Tickets are designed to be atomic and self-contained. Each ticket carries its complete implementation context: filesToCreate, filesToModify, codeReferences, typeReferences, inherited Patterns, resolved dependencies. The agent doesn't need to remember anything from previous tickets or earlier conversation turns. The ticket is the entire context. The schema is designed for intentional amnesia.