Ticket Format

Every sentence in a ticket is either a directive or a constraint. Nothing is decorative. Too much context drifts; too little hallucinates. This format is the sweet spot.

Standard fields

Field	Description
Problem Statement	What is broken or missing, and why it matters. 2-3 sentences max.
Parent Epic	Link to the parent epic, if applicable.
Effort Estimate	XS (< 1 hr), S (1-4 hr), M (4-8 hr), L (1-3 days), XL (3+ days).
Priority	P0 (drop everything), P1 (current sprint), P2 (next sprint), P3 (backlog).

The four Power Sections

A — Environment Context

Tell the agent where it is working. Tech stack, integration points, files to read first, files likely to be created or modified.

B — Guardrails

Tell the agent what not to do. Security constraints, performance targets, compatibility requirements, explicit prohibitions like “Do NOT modify the auth middleware.”

C — Happy Path

Tell the agent the input → logic → output flow. Numbered steps or a Mermaid diagram. One clear flow per ticket.

D — Definition of Done

Tell the agent how to prove it succeeded. Not “it works.” Not “tests pass.” Specific test assertions, lint and type-check gates, integration verification, a reviewer checklist.

A concrete example


TICKET: BACKEND-042 — Add /api/ping health-check endpoint

Problem Statement:
The deployment pipeline has no lightweight endpoint to verify the
service is running. We need a dedicated /api/ping endpoint that
returns JSON with zero middleware overhead.

Parent Epic: INFRA-010 (Observability and Health Checks)
Effort Estimate: XS
Priority: P1

--- A. Environment Context ---
- Stack: Next.js 15 / React 19 / TypeScript
- Existing pattern: follow app/api/health/route.ts
- Files to create:
    - CREATE app/api/ping/route.ts
    - CREATE __tests__/ping.test.ts

--- B. Guardrails ---
- Do NOT add authentication to this endpoint.
- Do NOT import any database or ORM modules.
- Response time must be < 10ms at p99.

--- C. Happy Path ---
1. Client sends GET /api/ping with no body, no auth.
2. Next.js App Router routes to the ping handler.
3. Handler returns HTTP 200 with body: {"ping": "pong"}
   Content-Type: application/json
4. No database call, no logging, no cache hit.

--- D. Definition of Done ---
- ping.test.ts asserts GET /api/ping returns 200 with the body above.
- npm run lint and npm run typecheck both return zero errors.
- PR reviewer can run `curl localhost:3000/api/ping` and see pong.