The acceptance criteria tell you what to build. The comments tell you why, and the why is the part you will need in six months.
Most people treat a ticket as a container for a task. User story at the top, acceptance criteria underneath, done when the box is ticked. Then it closes and everyone moves on. What is lost is the argument: the two options we considered, the reason we picked this one, the thing we deliberately decided not to do, and the constraint that made the obvious approach impossible.
That material almost never fits in an acceptance criterion. So it lives in a conversation, and then it evaporates.
An example from my own backlog. We spent real time on how URLs should work in the sequencer: whether a user’s page should be under their chosen name, what happens to the default slug before someone renames a sequence, why the random string in the URL was unacceptable. I wrote at the time that the strings "mean nothing to humans."
The eventual ticket said: implement slug-based URLs. Correct, and useless six months later, because it does not contain the reason. Without the reason, the next person to touch it, who might well be me, or might be an agent reading the ticket cold, will look at the slug logic, decide it is unnecessarily complicated, and simplify it straight back into the thing we deliberately moved away from.
This gets more important, not less, with AI in the loop, because agents are extremely good at reading a ticket and doing exactly what it says. They cannot infer the argument that produced it. If the ticket does not carry the reasoning, the reasoning does not exist as far as the work is concerned.
So I comment on tickets as the work moves, and I have stopped feeling self-conscious about talking to myself in public. What goes in:
The options we did not take, and why. Ten seconds to write, saves an afternoon of re-deciding.
Constraints discovered during the work. The thing that turned out not to be possible, or to be possible only at a cost nobody wanted.
Changes of mind, with the trigger. Not just that we changed direction but what made us. On 15 July I moved a feature out of a menu, then noticed the agent had already anticipated it and thanked it for the initiative. That belongs on the ticket, because the next person to wonder why that item is not in the menu deserves an answer.
What we deferred and what would bring it back. Far horizon is a legitimate answer. Silently dropping it is not.
There is a version of this that is over-documentation and I am not arguing for it. Nobody needs a transcript. What you need is enough that someone arriving cold can tell the difference between a deliberate decision and an accident.
Almost every piece of bad code I have inherited in twenty-five years was a deliberate decision whose reason had been lost.
Next: branches, merges, and why I do not tolerate loose ends.