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 to | Use |
|---|---|
| Write a ticket someone else can pick up and finish | This article |
| Make every ticket in the company follow one format | Ticket Standards |
| Learn what each field and button on a ticket does | Creating and editing tickets |
| Reuse the same ticket each cycle | Ticket templates |
| Break a large piece of work into parts | Epics, 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.
| Part | What it is | Example |
|---|---|---|
| Epic | The larger area or initiative | Payroll |
| Feature | The specific screen, flow or component | Payslips |
| Issue | A short label for the problem or the change, three to six words | Totals wrong after adjustment |
Put together: Payroll | Payslips - Totals wrong after adjustment.
| Weak title | Why it fails | Better | |
|---|---|---|---|
fix the emails not sending sometimes?? | No area, no feature, vague issue | `Leave | Approval emails - Not sent on weekends` |
Payslip issue | Says where, not what | `Payroll | Payslips - 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 recomputed | A summary, not a label | `Payroll | Payslips - 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.
| Field | Why it matters |
|---|---|
| Epic | Groups the work, so progress on an initiative can be seen |
| Sprint | Without one, the ticket never reaches a plan |
| Assignee | One real person. Two names means nobody owns it |
| Issue type | Bug, Story, Task or Improvement. It drives reports and filters |
| Priority | How urgent it is compared with everything else. See Statuses, priorities and ticket types |
| Story points | Its 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.