Ticket Writing

When to Use

• Writing a new epic, story, task, bug, or spike
• Reviewing a ticket before it enters sprint planning
• Auditing backlog items for clarity and actionability
• Decomposing an epic into ready-to-work stories
• Linking related tickets, dependencies, or blockers
• Coaching a team member on how to write better tickets

Guiding Principles

1. Any engineer can pick it up cold — The ticket must be self-contained. No oral lore required.
2. One clear outcome — A ticket should answer: "How will I know when this is done?"
3. Right size — A story should take 1–5 days. Split anything larger. Combine anything smaller.
4. Outcome over activity — Describe the result, not the steps to get there.
5. User language for stories, system language for tasks — Stories frame user value; tasks frame technical work.
6. Dependencies are explicit — Blocks, is-blocked-by, and relates-to links are set before the ticket enters the sprint.

Ticket Type Reference

Title Conventions

A good title is search-friendly, imperative, and specific — no jargon, no vagueness.

Format: [Verb] [object] [qualifying context if needed]

Rules:

• Start with a verb: Add, Fix, Refactor, Migrate, Remove, Update, Implement, Spike, Document
• Avoid acronyms unless universally known in your org
• Do not include sprint numbers or dates in the title
• Do not use "we should…" or "need to…" — write the action directly

Description Templates

Pick the template for the ticket type. Fill every section. Delete none.

Story Template

## Context

[1–3 sentences on why this work matters. What problem does it solve for the user?
Link to the parent epic and any relevant design doc or Confluence page.]

## User Story

As a [user persona],
I want to [specific action],
So that [concrete benefit].

## Acceptance Criteria

- [ ] [Specific, testable, binary condition]
- [ ] [Specific, testable, binary condition]
- [ ] [Specific, testable, binary condition]
(Add as many as needed. Each line must be independently verifiable.)

## Out of Scope

- [Anything explicitly NOT covered by this ticket]
- [Reference a separate ticket number if that work already exists]

## Notes / Open Questions

- [Any ambiguity or decision needed before work starts]
- [Link to relevant Slack thread, doc, or prior ticket if context exists]

Task Template

## Context

[1–3 sentences on why this technical work is needed. What breaks or degrades without it?
Link to the driving story or epic.]

## Work to Be Done

1. [Concrete implementation step]
2. [Concrete implementation step]
3. [Add tests / validation]

## Definition of Done

- [ ] [Specific, verifiable completion condition]
- [ ] [Specific, verifiable completion condition]
- [ ] Tests written and passing
- [ ] PR reviewed and merged

## Out of Scope

- [Anything explicitly not included]

## Notes / Open Questions

- [Unknowns, design constraints, or reference links]

Bug Template

## Summary

[One-sentence description of the defect and its impact.]

## Environment

- **Version / Branch**: [e.g., v2.3.1 / main]
- **Affected users**: [All users / logged-out users / admin role only]
- **Frequency**: [Always / intermittent — approx. X% of the time]
- **Severity**: [P1 — user blocked / P2 — workaround exists / P3 — cosmetic]

## Steps to Reproduce

1. [Step 1]
2. [Step 2]
3. [Observe the bug]

## Expected Behavior

[What should happen.]

## Actual Behavior

[What actually happens. Include error message, screenshot, or log snippet.]

## Root Cause (if known)

[Leave blank if unknown — fill in during investigation.]

## Fix Acceptance Criteria

- [ ] Reproducer no longer triggers the defect
- [ ] Regression test added
- [ ] No new errors introduced in related flows

## Linked Items

- Parent epic / story: [link or ticket number]
- Related bug reports: [link or ticket number]

Spike Template

## Question to Answer

[The single, specific question this spike must answer. If you have more than one question,
split into separate spikes.]

## Why This Matters

[What decision or work is blocked until this question is answered?]

## Time Box

**Maximum**: [1 day / 2 days] — Hard stop regardless of outcome.

## Success Criteria

By the end of this spike, we will have:
- [ ] A written recommendation (with rationale) for [question]
- [ ] Identified risks or unknowns for the recommended approach
- [ ] Updated [design doc / Confluence page / ticket description] with findings

## Approaches to Investigate

- Option A: [brief description]
- Option B: [brief description]

## Out of Scope

- Actual implementation (this is research only)

Writing Good Acceptance Criteria

Acceptance criteria (AC) define "done." Each criterion must be:

• Binary — Pass or fail, no judgment calls
• Testable — An engineer or QA can verify it without asking the author
• Specific — No vague words like "fast," "correct," or "appropriate"
• Scoped — Covers exactly this ticket, not adjacent functionality

Bad vs. Good AC

AC for Different Ticket Types

Stories — Frame in user-observable behavior:

- [ ] User can filter results by date range using start and end date pickers
- [ ] Selecting a date range updates results without a full page reload
- [ ] Invalid date ranges (end before start) display an inline validation error

Tasks — Frame in technical completion signals:

- [ ] Migration script runs idempotently (safe to run twice)
- [ ] All existing records have been backfilled with non-null `created_at` timestamp
- [ ] Rollback script documented in runbook

Bugs — Frame in "defect no longer reproducible":

- [ ] Steps to reproduce no longer trigger the 500 error
- [ ] New regression test added to the test suite
- [ ] Existing tests pass without modification

Decomposition Rules

Use these rules to decide when to split a ticket.

Split When…

Do Not Split When…

• The front-end and back-end are tightly coupled and cannot be tested independently
• The resulting pieces would not be independently deployable or reviewable
• The sub-tasks are so small they add more overhead than value (< 2 hours)

Decomposition Pattern

Epic: User can manage their notification preferences
  └─ Story: User can view their current notification settings
  └─ Story: User can enable or disable email notifications
  └─ Story: User can enable or disable push notifications
  └─ Story: User receives an in-app confirmation when preferences are saved
  └─ Task: Add notification_preferences table to DB schema
  └─ Task: Write migration to backfill defaults for existing users

Linking Dependencies

Dependencies must be explicit before a ticket enters a sprint. Undiscovered dependencies mid-sprint are a leading cause of carry-over.

Link Types

When to Link

• At creation time — If you know the dependency exists, link immediately
• During backlog refinement — Review parent epic links; check upstream service dependencies
• During sprint planning — Any ticket with an unresolved blocker link must stay in backlog
• After discovery — If a blocker surfaces mid-sprint, add the link immediately and surface to the team

Dependency Red Flags

• A ticket is in the sprint but its blocker is not scheduled — escalate immediately
• A ticket has no parent epic link — add it or create the epic
• Cross-team dependencies have no linked counterpart ticket in the other team's backlog — create a ticket there and link

Linking External Resources

Every ticket should link out to the information needed to work it. Do not make an engineer hunt.

Rule: If you had to open a tab to understand the scope, link that tab in the ticket.

Pre-Sprint Readiness Checklist

Before a ticket can be pulled into a sprint, it must meet all of the following:

• Title is imperative, specific, and jargon-free
• Type is set (Story / Task / Bug / Spike)
• Parent epic is linked
• Description is complete (no empty sections)
• Acceptance criteria are written (binary, testable, specific)
• Estimate is set (story points or days)
• Blocking and blocked-by links are set
• External resource links added where applicable
• Org-specific fields filled: component, label/tag, assignee, priority (see below)

Any ticket that fails this checklist goes back to backlog refinement, not into the sprint.

Org-Specific Configuration

The fields below are pluggable — substitute your org's values when using this skill. If your org has a verified connections file or private knowledge base, load that first and populate these before drafting tickets.

# ticket-writing org configuration
# Populate this for your org, then reference it when writing tickets.

tracker: jira                         # jira | linear | github-issues | servicenow | other
base_url: https://jira.example.com    # Your tracker's base URL

projects:
  default: ENG                        # Default project key/identifier
  infra: INFRA
  platform: PLAT
  # Add your org's project keys here

components:
  # Map to your org's component list (service names, layers, etc.)
  - api
  - frontend
  - data-pipeline
  - infrastructure

labels_or_tags:
  # Org-standard labels. Add/remove to match your label taxonomy.
  - tech-debt
  - customer-facing
  - security
  - compliance
  - performance
  - on-call-reduction
  - dependency                        # Cross-team dependency

priority_levels:
  # Align to your org's priority definitions
  p1: "User blocked, no workaround — fix in < 24h"
  p2: "Significant impact, workaround exists — fix this sprint"
  p3: "Minor issue or improvement — schedule in backlog"
  p4: "Cosmetic or nice-to-have — icebox until prioritized"

assignee_rules:
  # Document your org's conventions for initial ticket assignment
  unassigned_on_creation: true        # true = leave unassigned until sprint planning
  auto_assign_bugs_to: oncall         # oncall | triage-rotation | reporting-engineer
  spike_owner: requesting_em          # Who owns a spike: EM or senior engineer

story_points_scale: fibonacci         # fibonacci | linear | t-shirt
default_sprint_capacity_pts: 30       # Rough per-engineer capacity per 2-week sprint

custom_fields:
  # Add org-specific custom fields here
  # team: Platform Engineering
  # cost_center: "12345"

How to Use This Configuration

1. Store your completed config locally in a gitignored file, for example ticket-writing-config.yaml.
2. When the agent writes a ticket, reference the config to fill: project, component, labels, priority, and assignee.
3. If a field in the config is marked true for "unassigned on creation," do not set an assignee — leave it blank for sprint planning.
4. For auto_assign_bugs_to: oncall, look up the current on-call rotation before assigning.

Common Anti-Patterns

Ticket Audit Workflow

When auditing a backlog for quality, apply this checklist ticket by ticket:

1. Title — Is it imperative, specific, and < 80 characters?
2. Type — Is the right type selected?
3. Size — Is the estimate reasonable for the type? Needs splitting?
4. Description — Are all template sections filled?
5. AC — Is every criterion binary and testable?
6. Links — Parent epic, blockers, related tickets, and external docs linked?
7. Fields — Component, labels, priority, and assignee set per org config?
8. Staleness — Is this ticket > 90 days old with no activity? Archive or close.

Produce a summary following this format for any backlog audit:

## Backlog Audit — [Project] — [Date]

### Summary
- Total tickets reviewed: N
- Ready for sprint: N
- Needs refinement: N
- Recommend closing / archiving: N

### Needs Refinement (top issues)
| Ticket | Issue | Recommended Fix |
|--------|-------|----------------|
| [key] | Missing AC | Add acceptance criteria before next sprint planning |
| [key] | Estimate missing | Estimate during next refinement session |
| [key] | No parent epic | Link to [epic] or create a new epic |

### Recommend Closing
| Ticket | Reason |
|--------|--------|
| [key] | No activity in 6 months, superseded by [key] |