Notes · issue tracking
One issue is one issue.
Six rules for writing issues that move a project forward. I wrote them long before LLMs, to stop ticket threads that went on for weeks and settled nothing. They work just as well when the one picking up the ticket is a model.
-
01
If it’s not in the tracker, it doesn’t exist
If what you’re doing could be called a project, the first thing to set up is an issue tracker. Not a Word file, but a project in real issue-tracking software that everyone knows how to use.
Work starts if and only if an issue exists. That doesn’t mean you can’t take a client’s call about an outage. It means that when you put the phone down, you write the issue. Anything learned about an issue, by email, chat or in a hallway, goes into its comments. The whole team enforces this. Email and chat sound a siren’s call of simplicity, and nothing said there can be found later.
For a model An agent works from what’s in the tracker. It doesn’t see what was agreed in chat or on a call.
-
02
One issue is one issue
People like to write in lists, one stream of thought ending up in one issue. What’s easy for the writer is hard for everyone after them, because points from the same list can have different complexity, different owners, different priorities and different dependencies. Each grows its own comments, and the thread turns into the endless, opaque discussion everyone knows from email.
If you start writing a list, write several issues instead. When work on an issue turns up something new, don’t keep amending it: open a new issue and link the two.
For a model If an issue holds five problems, a model tends to fix some of them partly and report the job done.
-
03
Write it for someone who wasn’t there
Any reasonably competent reader should be able to reproduce the issue from what you wrote, without being part of the original team. Say what you wanted to do, what you did, what happened, and what should have happened. Add the environment if the screenshot doesn’t show it: which browser, which phone, which OS version.
A one-word title may be enough for today’s developer. More likely it starts a back-and-forth, and in three months it will mean nothing to anyone, the team included.
For a model A model knows nothing about the project beyond what you give it. The expected behaviour is also what it, or a test, checks the fix against.
-
04
Always include an uncropped screenshot
A full screenshot carries a lot: the browser and its version, the URL, the date and time, the operating system, the scroll position. Nobody cares that you have Facebook open in another tab. A crop of 100 by 100 pixels tells nobody anything. If the screenshot can’t show the URL, as on most phones, write it in the description.
Bounce issues that come without one. If a screenshot is hard to get, someone on the team can try to reproduce the problem and add one. If they can’t reproduce it, the issue goes back to whoever reported it.
For a model Models read screenshots well, and a full one answers questions the model would otherwise have to guess at.
-
05
The assignee moves it to resolution
If an issue is assigned to you, it’s yours to move: fix it, add what’s missing, check it, or hand it to whoever will work on it next. Issues often land with the wrong person. That isn’t the problem. The problem is when they aren’t reassigned quickly. Look at new assignments at least once a day and ask two questions: am I the right person, and do I have everything I need? If not, reassign it or ask. Before a holiday, keep the issues that can wait for you and reassign the rest.
For a model An agent can do the work, but a person still owns the issue and answers for what ships.
-
06
Whoever writes it can check the fix
Writing the issue isn’t the end of the road. Someone fixes it, and then the person who wrote it checks that it really is fixed, which they can’t do without understanding it. Issues often come from outside, from a client or a user. Before one goes into the tracker, someone on the team understands it well enough to reproduce it and writes down the steps.
For a model A model will usually report a fix as done. The person who wrote the issue decides whether it’s actually fixed.
The workflow
There are many workflows. This is one of the most basic. If the tool doesn’t reassign automatically, whoever changes the state reassigns the issue.
-
New
Written and waiting for triage.
-
In progress
Someone is working on it.
-
Resolved
Fixed, and reassigned to the reporter to verify. If it isn’t fixed, it goes back.
-
Closed
Verified, usually by whoever reported it.
Small rules that save a lot of time
- Write a title that sums up the issue. Most of the time people look at the board and don’t open the issue. With good titles, the board gives an overview of the whole project and saves a lot of clicking.
- Search first. It isn’t always obvious whether an issue was reported already, especially if it was already resolved. Spending a little time on it will make your team happier.
- Watch your spelling. Search won’t find a misspelled issue. As an extreme example, when the title says “dog” and the screenshot shows a cat, the team will spend time working out what the hell that means.
- Answer questions about your issues promptly. You want it resolved quickly, right?
- Don’t call it a bug. It may be a bug, a misunderstanding or a feature request. It’s an issue until it’s proven a bug. Don’t ask how it’s possible that we have an issue. Issues are inevitable and not always easy to fix.
- Keep the tone civil, on both sides. Harsh words, sarcasm and belittling don’t help anything get fixed. Reporters do it, and developers do it too. I was often on the developer side and was guilty of the same. If you’re annoyed, ask an LLM to remove the harsh words, sarcasm and belittling from your comment before you post it. Then check that it still says what you meant.
- Write in English. Next quarter the team may include a developer or a consultant who doesn’t speak your language. An LLM can translate for them, but most technical terms are English to begin with, and making one person run every comment through a translator is unnecessary friction.
And for whoever writes the code
- Push every day. Work that isn’t pushed doesn’t exist for anyone else. If there’s nothing to commit by the end of the day, perhaps you were reading, learning or writing docs, but you sure as hell weren’t coding.
- One commit is one change. It’s the same rule as one issue is one issue. Don’t push a new operating system as a single commit of 100,000 lines with no message.
- Deploy through CI/CD. A push to main goes to production automatically. No copying files by hand, and nobody reaches the servers except through Git.
Nabla, Samo Fortuna s.p.