The Contract

The ticket template is the bridge between worlds. Product Owners fill it. Developers build from it.

What It Is

Most tickets fail before development even starts. Something is vague, something is missing, something was assumed. The Contract changes that. It is a structured template that lives inside your ticket, forcing every decision to be written down: current behavior, desired behavior, testable requirements, before a single line of code is written.

The more specific the ticket, the better the blueprint, the better the code.

Goal

What are we building and why? One clear sentence. If you can't say it in one sentence, the scope is too big — split the ticket.

Anti-pattern

"Improve the dashboard"

Contract Ready

"Add a date range filter to the orders dashboard so managers can view sales by period"

Context

Why does this matter? What triggered this work? Detail the exact mechanics of the system as it stands, and how it should transform.

Current Behavior

How does the system work today? Be specific — reference pages, buttons, API endpoints, error messages.

Vague

"It's slow"

Explicit

"The /api/v1/orders endpoint takes 8s to resolve when fetching >10k rows. UI blocks entirely."

Desired Behavior

Define exactly what should happen after the change is implemented.

Vague

"Make it faster"

Explicit

"Paginate /api/v1/orders to 50 items. UI shows skeleton loader and resolves under 1s."

Requirements

Testable acceptance criteria. Each one must be verifiable — someone should be able to definitively say "yes, this works" or "no, it doesn't."

improve performance
Page loads in under 1 second on 3G network profiling
Table skeleton loader appears immediately while fetching

UI / UX

Filled by the Designer. Covers screens/flows, component choices (referencing existing components by name), and mockup attachments. Marked N/A if no design needed.

Figma Reference figma.com/file/1a2b3c/Orders-Dashboard-V2?node-id=0-1
Component Mapping

Use the existing DateRangePicker component. Filter appears inline above the table, same layout as the reports page.

Constraints

Non-negotiable rules. Performance budgets, browser support, backwards compatibility, security requirements.

Must not break existing API contracts — all v1 endpoints remain unchanged
No new dependencies — use existing date-fns library

Open Questions

Anything unresolved. This section MUST be empty before the ticket can move to Ready for Development. This is the hard gate.

Custom Fields

Type
feat | fix | improve | hotfix
Priority
Low | Medium | High | Critical
Status Flow
Draft Refining Designing Ready for Dev

Quality Gates

At Creation Soft Gate

Claude warns about missing or weak sections but still creates the ticket. Allows for iterative drafting.

At Transition Hard Gate

Claude blocks moving to Ready for Design/Dev if: Open Questions is not empty, Goal/Requirements are missing, or Behavior is vague.

Role Integration

Product Owners

Uses /draft to start a ticket. Claude leads the discussion, explores the codebase, and fills every section explicitly.

Designers

Fills the UI/UX section. References existing components by name from the codebase. Attaches exact mockups.

Developers

/scaffold

Parses the template to generate a blueprint. Maps Goal → Blueprint Goal. Flags weak sections or proceeds to code.