Writing Effective Tickets

The quality of the agent's output directly depends on the quality of the ticket description. Here's how to write tickets the agent handles well.

Structure

A good ticket description includes:

What — What needs to change or be built
Where — Which files, modules, or endpoints are involved
Why — Context for the change (helps the agent make design decisions)
Acceptance criteria — How to verify the work is complete

Example: good ticket

markdown

## Description

Add a rate limiter to the /api/upload endpoint. Currently any
authenticated user can upload unlimited files, which risks
storage exhaustion.

## Requirements

- Limit to 10 uploads per user per hour
- Use an in-memory counter (no Redis needed)
- Return HTTP 429 with a Retry-After header when limit is exceeded
- Add a test for the rate limiting behavior

## Files involved

- internal/handlers/upload.go (add middleware)
- internal/handlers/upload_test.go (new tests)

Example: weak ticket

markdown

Fix the upload thing, it's too slow and people abuse it.

This gives the agent no direction on what "fix" means, what "too slow" means quantitatively, or what "abuse" looks like.

Choosing the right kind

The ticket kind changes the agent's methodology:

Kind	Use when	Agent behavior
Bug	Something is broken	Reproduce → diagnose root cause → minimal fix → regression test
Feature	Building something new	Design → plan → implement incrementally → test → document
Task	General work item	Understand → plan → implement → test
Chore	Refactoring, cleanup, deps	Assess scope → plan order → systematic changes → verify no regressions

Choosing the right priority

Priority affects reasoning depth and approach:

Priority	Use when	Agent behavior
Urgent	Production is down	Fastest correct fix. Skips exploration. Low reasoning effort.
High	Important, needs attention soon	Efficient but thorough. Medium reasoning.
Medium	Normal work	Balanced. Default.
Low	Nice to have, quality matters	Takes time. Explores broadly. Considers refactoring. High reasoning.

Tips

Be specific about file locations. The agent can find code on its own, but pointing it to the right files saves time and tokens.
Include error messages. For bugs, paste the exact error. The agent greps for it.
Mention tests. If you want tests written, say so explicitly. Specify the testing framework if it matters.
Set constraints. "Don't modify the public API" or "Must be backward compatible" prevents unwanted changes.
One concern per ticket. Don't combine unrelated changes. The agent works best with focused scope.
Reference other tickets. "Similar to #12" or "This is the backend for #15" gives the agent context. It can look up other tickets with the get_ticket tool.