Documentation

Write tickets agents can act on

Turn intent into observable, bounded acceptance criteria and specification clauses that an agent can implement and verify without guessing.

Use the real ticket contract

A ticket's type-specific content field is ticket_type. Acceptance criteria and specifications are modeled as first-class specification clauses attached to the ticket via spec_clauses, rather than unstructured content fields. Put one independently verifiable condition in each clause.

The title should name the outcome, and the description should explain the user or operational problem. Keep implementation instructions out of specification clauses unless a specific mechanism is itself a requirement.

Make every criterion observable

Write conditions that can be proved from product behavior, an API response, persisted data, a rendered state, or a named automated check. Include the relevant input, boundary, and expected result.

  • • Name the actor or starting state when it changes the outcome.
  • • Use exact field names, routes, limits, or state transitions when they are part of the contract.
  • • Cover the failure or boundary case that would make a happy-path implementation incomplete.
  • • Say what evidence proves completion; do not use vague phrases such as works correctly or handles edge cases.

Separate completion from scope boundaries

Specification clauses describe what must be true. If a dependency must land first, link it with depends_on rather than hiding it in prose.

Do not add criteria for unrelated cleanup just because the same files are nearby. Create another ticket and link it when that work has independent value or validation.

Example: an agent-ready bug ticket

This example names the affected viewport, the visible result, the regression boundary, and the evidence expected from the implementation.

Ticket payload

{
  "type": "ticket",
  "title": "Make finding-rating actions responsive on mobile",
  "content": {
    "ticket_type": "bug"
  },
  "spec_clauses": [
    "At a 390px viewport, every finding-rating action is visible without horizontal page scrolling.",
    "Keyboard focus can reach each action and its visible focus indicator is not clipped.",
    "Existing desktop finding-rating stories have no visual changes outside the action layout.",
    "A mobile Storybook regression story covers the longest supported action labels."
  ]
}

Check the ticket before handing it to an agent

An agent-ready ticket has a valid parent, an accountable owner, a priority when sequencing matters, and enough context in its chain to explain why the work exists. Its criteria cover the full intended behavior and can be checked against authoritative evidence.

  • • Each criterion has one clear pass or fail result.
  • • The set covers success, the important boundary, and regression expectations.
  • • No criterion depends on unstated design or product decisions.
  • • The ticket can move to closed with closure_reason completed only after every criterion is proved.