Writing a good ticket

Writing a good ticket

A ticket is a brief for someone who wasn't in the room when the work was agreed. It also stays on record as the reason the work was done. A good ticket lets the assignee start without asking you anything, and lets someone six months from now see why the change was made.

This article shows one way of writing tickets that works across every ticket type: a fixed title pattern, a three-part description, and a short list of fields to fill before the ticket counts as ready.

Where: any ticket page in KAMI Tasks

You need: access to the project. See Projects and access

When to use this, and when not to

You want toUse
Write a ticket someone else can pick up and finishThis article
Make every ticket in the company follow one formatTicket Standards
Learn what each field and button on a ticket doesCreating and editing tickets
Reuse the same ticket each cycleTicket templates
Break a large piece of work into partsEpics, subtasks and linked tickets

1. The title: Epic | Feature - Issue

A title should tell a reader three things at a glance: which area of the product the ticket belongs to, which part of that area, and what is wrong or needed.

PartWhat it isExample
EpicThe larger area or initiativePayroll
FeatureThe specific screen, flow or componentPayslips
IssueA short label for the problem or the change, three to six wordsTotals wrong after adjustment

Put together: Payroll | Payslips - Totals wrong after adjustment.

Weak titleWhy it failsBetter
fix the emails not sending sometimes??No area, no feature, vague issue`LeaveApproval emails - Not sent on weekends`
Payslip issueSays where, not what`PayrollPayslips - Totals wrong after adjustment`
When an admin edits an adjustment after the payroll has been computed, the payslip total doesn't update until the payroll is recomputedA summary, not a label`PayrollPayslips - Stale total after adjustment edit`

The Issue part is a label, not a summary. The detail belongs in the description.

💡 If your company has Ticket Standards set up, press Fix title to standard on any ticket and KAMI AI rewrites the title into your format. Nothing changes until you accept.

2. The description: Issue, Solution, Implementation

Every description has the same three sections, in this order.

Issue (or Objective for new work): what is wrong or missing, and who it affects. Say what happens now and what should happen instead. For a bug, include the steps to reproduce it, the company or record where you saw it, and a screenshot if you have one.

Solution: what the finished result looks like from the user's side. Describe the behaviour, not the code. This is the part people agree on before work starts, so state one clear answer rather than a list of options.

Implementation: how it will be built, and what "done" means. List the screens, settings or records that change, anything that must not change, and the checks that prove it works. Leave this short if the assignee is better placed to decide. They fill it in as they plan.

A short example:

Issue When an admin edits an adjustment after payroll is computed, the employee's payslip still shows the old total until someone recomputes payroll. Employees see the wrong net pay in the meantime. Solution Editing an adjustment recomputes that employee's payslip straight away. The payslip and the payroll summary always show the same total. Implementation - Recompute only the affected employee, not the whole payroll - Locked or approved payrolls stay locked: the edit is refused, as it is today - Done when: an edited adjustment changes the payslip total with no manual recompute
💡 The description's AI menu can help. Generate from title drafts a description, Add acceptance criteria appends a done-when list, and Rewrite from comments folds an agreed change back into the description. Each shows the result first, and you choose whether to keep it. The AI only restructures what is already in the ticket, so a one-line ticket still comes back thin.

3. Fill these fields before the ticket is ready

A ticket missing any of these isn't ready to be worked on. It is a note.

FieldWhy it matters
EpicGroups the work, so progress on an initiative can be seen
SprintWithout one, the ticket never reaches a plan
AssigneeOne real person. Two names means nobody owns it
Issue typeBug, Story, Task or Improvement. It drives reports and filters
PriorityHow urgent it is compared with everything else. See Statuses, priorities and ticket types
Story pointsIts size, which feeds sprint velocity. See below

Add a due date to anything that has a real deadline. A ticket with no due date never shows as overdue.

4. Sizing with story points

Agree as a team on what one point means, write it into your Ticket Standards, and size every ticket against that same measure. A simple one that works: one point is about one hour of the assignee's own time to plan, do, review and test the work.

  • Size the people time, not the size of the change. One component reused on many screens can be a small ticket.
  • If you can't size it because a decision hasn't been made, the ticket is blocked, not bigger. Record the open decision, ask whoever owns it, and size the ticket once it's answered.
  • Large estimates are a sign to split the ticket. Move the parts into subtasks or separate tickets under the same epic, so each one can be finished and checked on its own.

The time estimate itself goes in Original estimate. See Estimates and logging time.

What Happens Next

  • Once the assignee and sprint are set, the ticket appears on the board and on the assignee's My Work.
  • The assignee and watchers are notified. See Notifications in KAMI Tasks.
  • If GitLab is connected, a branch named after the ticket key (for example KDV-123-Payslip-totals) links its merge requests back to the ticket. See Integrations.

Tips

  • Write for someone who wasn't in the meeting. If the ticket only makes sense with context in your head, it isn't finished.
  • One ticket, one outcome. If the Solution section describes two separate results, write two tickets.
  • Keep the description current. When plans change in the comments, update the description with Rewrite from comments. The next reader reads the description, not every comment.
  • Link, don't repeat. Point to the related ticket, epic or help article instead of copying its content.
  • State the answer. "Should we do A or B?" belongs in a comment to the decision owner. The Solution section records the decision.

Troubleshooting / FAQ

Q: Fix title to standard gives a vague title. The ticket doesn't contain the information the format needs. Add the area and the feature to the description, then try again.

Q: The Fix to standard actions are greyed out. Your company hasn't set up Ticket Standards yet. A project admin can add them under Settings › Ticket Standards. See Ticket Standards.

Q: My ticket has no merge requests showing. The branch name must start with the exact ticket key, for example KDV-123-…. See Integrations.

Related articles