Ticket Craft

• Independent Can this be completed without waiting on another ticket? Blocked by undocumented dependencies N
• Negotiable Is there room to adjust implementation approach? Over-specifies implementation details V
• Valuable Can you articulate who benefits and how? No clear user or business value E
• Estimable Does the team understand enough to size it? Too vague or too large to estimate S
• Small Can one person finish this in 1-3 days? More than 5 acceptance criteria T
• Testable Can you write a pass/fail test for it? Uses vague language like "fast" or "good UX" C
• Claude-Ready Can an AI agent execute this without clarifying questions? Missing file refs, patterns, verification, or constraints Ticket Types

1. Feature Ticket

[PROJ-XXX] {Verb} {Feature} for {User}

Type: Feature Priority: {Critical | High | Medium | Low} Points: {1 | 2 | 3 | 5 | 8} Labels: {frontend, backend, api, database, etc.} Epic: {Parent epic}

User Story

As a {specific persona}, I want to {specific action}, so that {measurable benefit}.

Background

{1-2 paragraphs on why this matters. Link to product brief, user research, or business justification. Include any relevant metrics or user feedback.}

Acceptance Criteria

AC1: {Happy path scenario} Given {precondition}, when {action}, then {expected result}. AC2: {Edge case / error scenario} Given {precondition}, when {action}, then {expected result}. AC3: {Boundary condition} Given {precondition}, when {action}, then {expected result}.

Out of Scope

{Explicitly state what this ticket does NOT include}

{Prevents scope creep and keeps ticket small}

Claude Code Context

Relevant Files (read these first)

src/services/example.ts

• Existing service to extend

src/models/example.ts

• Data model definition

src/api/routes/example.ts

• Existing endpoint patterns to follow

Pattern Reference

Follow the pattern in src/services/user.ts for service layer implementation. Follow the pattern in src/api/routes/users.ts for route definition. Follow the pattern in tests/services/user.test.ts for test structure.

Database Changes

{Table to create/modify, columns, types}

{Migration file location: supabase/migrations/ or prisma/migrations/ }

{RLS policies if using Supabase}

API Contract

POST /api/{resource} Request: { field1: string, field2: number } Response: { id: string, field1: string, created_at: string } Error: { error: string, code: number }

Constraints

• Do NOT modify {specific files or modules}
• Do NOT add new dependencies without approval
• Follow existing error handling in src/core/exceptions.ts
• {Any performance budgets: response time < 200ms, bundle size < 50KB}

Verification

# Run specific tests
npm test -- --grep "{feature name}"

# Lint check
npm run lint

# Type check
npm run typecheck

# Full validation
npm test -- --coverage
Environment Variables
Existing: {list vars already in .env that are relevant}
New required: {list any new vars needed}
Dependencies
Blocked by: {PROJ-XXX} ({brief description})
Blocks: {PROJ-YYY} ({brief description})
Design
Mockup: {link to Figma/design if applicable}
---

### 2. Bug Ticket

```markdown
## [BUG-XXX] Fix: {Component} - {Symptom}

**Type:** Bug
**Priority:** {Critical | High | Medium | Low}
**Points:** {1 | 2 | 3 | 5}
**Labels:** {regression, ux-bug, data-bug, security-bug}
**Severity:** {Blocks users | Degrades experience | Cosmetic}

---

### Bug Summary
{One sentence: what is broken and who is affected.}

### Environment
- Browser/OS: {e.g., Chrome 120 / macOS 14.2}
- Environment: {Production | Staging | Local}
- User type: {Anonymous | Authenticated | Admin}
- First observed: {date}

### Steps to Reproduce
1. {Navigate to / perform action}
2. {Perform next action}
3. {Perform next action}
4. **Observe:** {incorrect behavior}

### Expected Behavior
{What should happen instead.}

### Actual Behavior
{What actually happens. Include error messages, console output, screenshots.}

### Impact
- Users affected: {percentage or count}
- Frequency: {every time | intermittent | specific conditions}
- Workaround: {exists / none}

---

### Claude Code Context

#### Suspected Root Cause
{Where the bug likely lives, if known.}
- File: `src/components/LoginForm.tsx:87`
- Issue: `isSubmitting` state set to `true` on validation error but never reset

#### Relevant Files
- `src/components/LoginForm.tsx` - Form component with the bug
- `tests/components/LoginForm.test.tsx` - Existing tests (gap here)
- `src/hooks/useAuth.ts` - Auth hook used by the form

#### Test Gap Analysis
- Existing tests cover: {what's currently tested}
- Missing test: {what test would have caught this bug}

#### Bug Fix Workflow (TDD)
1. Write a failing test that reproduces the bug
2. Verify the test fails (confirms the bug exists)
3. Fix the bug with minimum code change
4. Verify the test passes
5. Run full test suite to check for regressions

#### Verification
```bash
# Run the specific test
npm test -- --grep "LoginForm submit"

# Run related tests
npm test -- src/components/LoginForm.test.tsx

# Full regression check
npm test
Constraints
Fix the bug only - do NOT refactor surrounding code
Do NOT change the component's public API
Ensure all existing tests continue to pass
---

### 3. Tech Debt Ticket

```markdown
## [TECH-XXX] Refactor: {Area} - {Improvement}

**Type:** Tech Debt
**Priority:** {High | Medium | Low}
**Points:** {3 | 5 | 8}
**Labels:** {refactor, performance, maintainability, testing}

---

### Problem Statement
{What is wrong with the current implementation and why it matters.
Include concrete pain points: slow CI, frequent bugs, developer confusion.}

### Current State
- File: `{path}` ({N} lines)
- Test coverage: {X}%
- Cyclomatic complexity: {N}
- Related bugs: {PROJ-XXX, PROJ-YYY}
- Pain frequency: {how often this causes issues}

### Proposed Change
{What specifically should change and why this approach.}

### Acceptance Criteria
- [ ] {Specific structural change completed}
- [ ] All existing tests pass without modifying test assertions
- [ ] No public API changes (existing consumers unaffected)
- [ ] Test coverage >= {X}%
- [ ] {Measurable improvement metric}

### Risk Assessment
- Risk level: {Low | Medium | High}
- Mitigation: {run full regression, deploy behind flag, etc.}

### Business Justification
{Why this is worth doing now. E.g., "Reduces average bug fix time from 4h to 1h"
or "Enables upcoming feature PROJ-XXX which requires clean separation."}

---

### Claude Code Context

#### Relevant Files
- `{file}` - Current implementation to refactor
- `{test file}` - Existing tests (must not break)
- `{dependent file}` - Consumer of the API being refactored

#### Pattern Reference
Follow the pattern established in `{good example file}` for the new structure.

#### Constraints
- Do NOT change public APIs or exports
- Do NOT modify test assertions (tests should pass as-is)
- Do NOT introduce new dependencies
- Keep backwards compatibility

#### Verification
```bash
# Existing tests must pass unchanged
npm test

# No type errors
npm run typecheck

# Lint clean
npm run lint

# Coverage target
npm test -- --coverage
---

### 4. Epic Breakdown Ticket

```markdown
## [EPIC-XXX] {Epic Name}

**Type:** Epic
**Priority:** {Critical | High | Medium}
**Target:** {Sprint/milestone}

---

### Objective
{One paragraph: what this epic achieves and why it matters.}

### Success Metrics
- {Measurable outcome 1}
- {Measurable outcome 2}

### User Workflows
{The user journey this epic covers, broken into steps.}
1. {Step 1: Discovery/Entry}
2. {Step 2: Core Action}
3. {Step 3: Completion/Result}

### Ticket Breakdown

| # | Ticket | Type | Points | Dependencies |
|---|--------|------|--------|-------------|
| 1 | {title} | Feature | 3 | None |
| 2 | {title} | Feature | 5 | #1 |
| 3 | {title} | Feature | 3 | None |
| 4 | {title} | Feature | 2 | #2, #3 |
| 5 | {title} | Tech Debt | 3 | None |

### Slicing Strategy
{How the epic was broken down. Reference the technique used.}

### Agent Team Mapping
{If using agent teams, how features map to agents.}
- Feature Agent 1: Tickets #1, #2
- Feature Agent 2: Tickets #3, #4
- Parallel execution: #1 and #3 can run simultaneously
- Sequential: #2 depends on #1, #4 depends on #2 and #3
Epic Slicing Techniques
When breaking an epic into tickets, use one of these strategies:
Technique
When to Use
Example
By workflow step
Clear user journey
Browse > Play > Save > Share
By data variation
Multiple data types
Text posts, images, videos
By user role
Different permissions
Anonymous, authenticated, admin
By CRUD
Data operations
Create, Read, Update, Delete
Happy path first
Incremental delivery
Success flow first, then errors
By boundary
System integration
Frontend, API, database separately
Rules of Thumb
Each ticket:
1-3 days
of work for one developer/agent
More than
5 acceptance criteria
= split the ticket
More than
8 story points
= definitely split
Every ticket should be
independently deployable
(even behind a flag)
Order tickets:
simplest, most foundational first
The Claude Code Ready Checklist
Before a ticket is ready for an AI agent to execute, verify:
┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE CODE READY CHECKLIST                                     │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  CONTEXT                                                         │
│  ☐ Relevant files listed with full paths                         │
│  ☐ Pattern reference points to a real file to follow             │
│  ☐ API contract defined (request/response shapes)                │
│  ☐ Database changes specified (tables, columns, migrations)      │
│  ☐ Environment variables listed (existing + new)                 │
│                                                                  │
│  SCOPE                                                           │
│  ☐ Out of Scope section explicitly states what NOT to do         │
│  ☐ Constraints section lists files/modules NOT to modify         │
│  ☐ Ticket covers one logical change (atomic)                     │
│  ☐ Estimable at ≤ 5 story points                                │
│                                                                  │
│  VERIFICATION                                                    │
│  ☐ Test command provided (exact command, not "run tests")        │
│  ☐ Lint command provided                                         │
│  ☐ Typecheck command provided                                    │
│  ☐ Acceptance criteria are Given-When-Then or checkboxed         │
│  ☐ Each criterion is independently pass/fail testable            │
│                                                                  │
│  QUALITY                                                         │
│  ☐ Title is imperative verb + object + context                   │
│  ☐ Title under 80 characters                                     │
│  ☐ Description explains WHY, not just WHAT                       │
│  ☐ 2-5 acceptance criteria (not more)                            │
│  ☐ No vague language ("fast", "good UX", "clean")               │
│                                                                  │
│  If any box is unchecked, the ticket is NOT ready.               │
└─────────────────────────────────────────────────────────────────┘
Anti-Patterns (Never Do These)
1. The Title-Only Ticket
Title: Fix login
Description: (empty)
Why it fails:
No context, no acceptance criteria, no file references. Claude Code will guess and likely guess wrong.
2. The Novel
Title: Implement new onboarding
Description: (3 pages mixing UI, backend, analytics, email, and future ideas)
Why it fails:
Not small, not independent. Agent teams can't parallelize this. Split into 5+ tickets.
3. The Vague Requirement
Acceptance Criteria:
- Should be fast
- UX should be good
- Should work on mobile
Why it fails:
Unmeasurable, untestable. Replace with: "Response time < 200ms", "Passes WCAG 2.1 AA", "No horizontal scroll at 320px viewport."
4. The Over-Specified Solution
Title: Use Redis to cache user sessions
Description: Install Redis, configure connection pooling, set TTL to 3600...
Why it fails:
Prescribes the solution instead of the problem. Should describe "Session lookups take 500ms, need < 50ms" and let the agent choose the approach.
5. The Missing Files Ticket
Description: Update the auth module to support OAuth.
Why it fails for AI:
"The auth module" could be 20 files. Claude Code needs:
src/services/auth.ts
,
src/middleware/auth.ts
,
src/routes/auth.ts
- specific paths.
6. The No-Verification Ticket
Acceptance Criteria:
- OAuth login works
- Users can sign in with Google
Why it fails:
No test command, no verification steps. Claude Code performs dramatically better when it can verify its own work.
Good vs Bad Examples
Bad: Vague Feature Ticket
Title: Add rate limiting to the API
Description: We need rate limiting on our endpoints.
Good: Claude Code Ready Feature Ticket
Title: Add sliding window rate limiter to /api/generate endpoint

User Story:
As an API consumer, I want requests to be rate-limited
so that the service remains available under heavy load.

Acceptance Criteria:
AC1: Given an authenticated user making requests,
     when they exceed 10 requests per minute,
     then return 429 with Retry-After header.

AC2: Given a rate-limited user,
     when the window expires,
     then requests succeed again.

AC3: Given an unauthenticated request,
     when it hits /api/generate,
     then return 401 (rate limiting only applies to authed users).

Claude Code Context:
- Pattern: Follow `src/middleware/throttle.ts` for middleware structure
- File: Create `src/middleware/rateLimit.ts`
- Test: Create `tests/middleware/rateLimit.test.ts`
- Route: Modify `src/api/routes/generate.ts` to add middleware
- Constraint: Do NOT modify existing middleware or other endpoints

Verification:
  npm test -- --grep "rate-limit"
  npm run lint
  npm run typecheck
Mapping Tickets to Agent Teams
When using the agent-teams workflow, tickets map directly to the 10-task pipeline:
Ticket Section
Maps To
Agent
Title + Description
Task 1:
{name}-spec
Feature Agent
Acceptance Criteria
Task 3:
{name}-tests
Feature Agent (writes tests from AC)
Pattern Reference
Task 5:
{name}-implement
Feature Agent (follows pattern)
Verification section
Task 6-7: verify + validate
Quality Agent + Feature Agent
Constraints
Enforced throughout
All agents
Claude Code Context
Loaded at start
Feature Agent reads first
Ticket → Agent Team Flow
1. Create ticket using templates above
2. Ticket becomes the feature spec in _project_specs/features/
3. Team Lead reads spec, creates 10-task dependency chain
4. Feature Agent uses ticket's Claude Code Context to start
5. Quality Agent uses ticket's Acceptance Criteria to verify
6. Review Agent reviews against ticket's Constraints
7. Security Agent scans based on ticket's scope
8. Merger Agent creates PR referencing the ticket ID
Ticket Title Conventions
Type
Format
Example
Feature
Add {feature} for {user}
Add episode bookmarking for listeners
Enhancement
Improve {what} in {where}
Improve search performance in episode feed
Bug
Fix: {Component} - {Symptom}
Fix: PlayerBar - audio stops on tab switch
Tech Debt
Refactor: {Area} - {Goal}
Refactor: AuthService - extract token management
Security
Security: {What} in {Where}
Security: add input sanitization to comment API
Chore
Chore: {What}
Chore: upgrade React from 18 to 19
Rules:
Start with an imperative verb (Add, Fix, Improve, Refactor, Remove)
Under 80 characters
Include the component/area affected
Be specific enough to distinguish from other tickets
Story Points for AI Agents
AI agents estimate differently than humans. Use this calibration:
Points
Scope
Agent Time
Example
1
Single file, < 20 lines changed
~5 min
Fix a typo, update a config value
2
1-2 files, straightforward
~15 min
Add a field to a form, update an API response
3
2-4 files, clear path
~30 min
New API endpoint following existing pattern
5
4-8 files, some decisions
~1 hour
New feature with tests, models, and routes
8
8+ files, complex
~2 hours
Integration with external service, new data model
13
Too large, split required
-
Full authentication system, major refactor
Rule:
If > 5 points, consider splitting. If 13, always split.
Integration with Ticket Systems
Jira
Use custom field "Claude Code Context" for the AI-specific section
Use labels:
claude-ready
,
needs-context
,
ai-blocked
Link tickets with "blocks/blocked by" for dependency chains
Asana
Use custom fields for Priority, Points, Type
Use subtasks for the 10-task pipeline steps
Use tags:
claude-ready
,
needs-refinement
Linear
Use issue templates with the Claude Code Context section built-in
Use labels for ticket type and claude-readiness
Use projects to group tickets into epics
GitHub Issues
Use issue templates (
.github/ISSUE_TEMPLATE/
)
Use labels:
feature
,
bug
,
tech-debt
,
claude-ready
Use milestones for epics
Command: /create-ticket
When the user asks to create a ticket, follow this workflow:
Step 1: Gather Context
Ask the user:
What type? (Feature / Bug / Tech Debt)
Brief description of what needs to be done
Which part of the codebase is involved?
Step 2: Auto-Detect Context
Read the relevant files to understand current implementation
Identify the pattern to follow from existing code
Find existing tests to understand test conventions
Check for related files that might be affected
Step 3: Generate Ticket
Use the appropriate template above, filling in:
All Claude Code Context fields (auto-detected)
Acceptance criteria (derived from description)
Verification commands (from project's CLAUDE.md or package.json)
Constraints (based on codebase analysis)
Step 4: Validate with Checklist
Run the Claude Code Ready Checklist against the generated ticket.
Flag any unchecked items for the user to address.
Step 5: Output
Present the ticket in the template format, ready to paste into Jira/Asana/Linear.
Definition of Ready (for Sprint)
A ticket can enter a sprint when:
Passes INVEST+C criteria
Claude Code Ready Checklist is complete
Dependencies are identified and unblocked
Story points assigned
Design/mockups attached (if applicable)
Acceptance criteria reviewed by team
Definition of Done
A ticket is done when:
All acceptance criteria verified (pass/fail)
Tests written and passing
Code reviewed (no Critical/High issues)
Security scan passed
Lint and typecheck clean
Coverage >= 80% for new code
PR created with full pipeline results
Documentation updated (if applicable)