Skip to main content

Design good tickets

Good ticket design makes work easier to assign, review, filter, and finish. Use this guide before creating important delivery, customer, bug, or operations work.

Start with the outcome​

  1. Write the title as the desired result.
  2. Put the most important object first.
  3. Avoid titles that only describe activity.

Good titles:

  • Fix invite expiry validation for organisation admins
  • Add launch checklist to Enterprise onboarding docs
  • Investigate slow snapshot generation on large workspaces

Weak titles:

  • Invites
  • Docs update
  • Look at snapshots

Write the description​

  1. Start with one short paragraph explaining why the work matters.
  2. Add acceptance criteria as bullets.
  3. Add constraints, links, or reference IDs.
  4. Name known blockers or dependencies.
  5. Add test, review, or rollout notes when they are known.

Example:

Customers cannot tell whether invite links are expired before sending them to teammates.

Acceptance criteria:
- Expired invites show an explicit expired state.
- Admins can create a replacement invite from the same row.
- The invite table keeps the original invited email visible.

References:
- DEC-18 invite expiry policy
- RISK-7 onboarding support burden

Choose the right type​

  1. Use task for concrete work.
  2. Use bug when existing behavior is broken.
  3. Use story when the work is framed around a user outcome.
  4. Use subtask when the item belongs under another ticket.
  5. Use an epic for a larger outcome that contains multiple tickets.

Do not use issue type as a priority signal. Priority belongs in the priority field.

Set priority deliberately​

  1. Use a lower priority number for more urgent work.
  2. Compare against other active tickets before setting P1 or P2.
  3. Add a reason in the description or a comment when priority is high.
  4. Revisit priority during standup or weekly review.

High priority without rationale becomes noise. Put the reason where the team can audit it later.

Add labels only when they help repeated review​

  1. Use short lowercase labels such as backend, security, customer, or launch.
  2. Prefer a custom field when the values need controlled reporting.
  3. Avoid one-off labels that only one person understands.
  4. Review label filters periodically and remove stale patterns from active work.

Use labels for flexible tags. Use custom fields for structured values the team will maintain.

Fill custom fields for the board you use​

  1. Check which saved board will review the ticket.
  2. Fill the custom fields shown on that board's cards.
  3. Fill required custom fields before moving the ticket through restricted transitions.
  4. Use controlled options exactly as defined by the project.

If reviewers keep opening tickets to find the same information, add that field to the board card layout.

Connect the ticket to larger context​

  1. Add a parent or epic when the work is part of a larger outcome.
  2. Link blockers and related tickets.
  3. Mention docs, decisions, risks, memory, or snapshots by display ID when they explain the work.
  4. Add a comment for handoff context that does not belong in the main description.

Connections make tickets useful to AI-assisted review and later operating decisions.

Keep the ticket small enough to finish​

Split the ticket when:

  1. More than one owner needs to move independently.
  2. The acceptance criteria describe separate releases.
  3. Part of the work is blocked and part is ready.
  4. Reviewers cannot tell what completion means.
  5. The ticket keeps carrying over without progress.

Use subtasks or sibling tickets under an epic instead of letting one ticket become a vague project.

Pre-flight checklist​

Before you save a high-value ticket:

  1. The title names the result.
  2. The description explains why the work exists.
  3. Acceptance criteria are testable.
  4. Type, priority, owner, dates, labels, and custom fields are intentional.
  5. The parent, epic, links, and references are connected.
  6. A reviewer could decide whether the work is done without asking the author.

Related guides: Create and update tickets, Link and organize tickets, Add custom fields.