Issue

When work traveled by word of mouth, requests piled up wherever they happened to land. Some came out of a meeting, some sat in the middle of a chat thread, and some were a sentence someone said in passing on the way to lunch. Everyone kept their own notes, so nobody could say how many open requests the team was carrying.

Things fell through the cracks, which was expected. The more irritating version was discovering just before a release that two people had been doing the same work. Nothing recorded who had picked it up, so both of them assumed it was theirs.

The gap always showed up as the same conversation. "What happened with that thing I mentioned last week?" "Which thing?" After the explanation came the second half: "Oh, I thought someone else had taken that." The person asking remembered saying it, and the person listening never registered it as a request at all.

An issue exists to collect all of that in one place. The important part is that it doesn't care what kind of work it holds. Building a feature, fixing something broken, and answering a customer request all get filed the same way, and what's left is a single list instead of scattered conversations. A list can be scanned, counted, and handed out.

Tools name the fields differently, but an issue generally carries five things.

1. Title — the one line visible in the list. "Password reset email never arrives" beats "login bug" because someone scanning the list can tell the items apart without opening them.
2. Description — why the work is needed and the situation it shows up in. For a bug, that means steps to reproduce, the expected behavior, and the actual behavior side by side.
3. Acceptance criteria — what has to be true before the issue can be closed. Without this line, the person who filed it and the person doing it work toward different endings.
4. Size estimate — how large the work is. Planning adds these up to judge how much fits in the next cycle.
5. Links — the relationship to a parent or to related items. Hang it under a larger chunk like an epic and that chunk's progress percentage comes out on its own.

Item 3 is the one that actually goes missing. Titles and descriptions get written naturally in the act of filing, while acceptance criteria get skipped because the writer assumes the reader obviously knows them too.

Four more values attach to each issue. Workflow status says which stage it sits in, assignee says who owns it, due date says when it was promised, and labels are the tags used to gather related items later. Filling these in isn't about keeping records tidy; it's about being able to ask questions later. Assignees have to be set before you can see that eight items landed on one person, and labels have to be applied consistently before you can count how many days this quarter went into paying down technical debt.

Issues aren't an engineering-only artifact. Sales files one after a customer email, a designer files one after spotting a screen that drifted from the design, and a product manager files the decisions that came out of a meeting. Restrict filing rights to engineers and everyone else goes back to asking over chat, which dissolves the whole point of having one list.

Three kinds of people read them. The assignee reads to see what to build and where it stops. Whoever plans the cycle reads to see how many items remain and how big they are. And six months later, someone reads to find out why a feature was built this way. That third reader is what turns an issue into a record.

The fact that writer and reader are different people is where the craft comes in. At the moment of filing, all the context is in your head and a title seems like plenty. Three days later, someone else has only that title. An issue that says "fix that thing" is a mystery even to the person who wrote it a month on. Writing down which screen, what was clicked, what appeared, and what should have appeared takes three lines, and those three lines replace half a dozen follow-up messages.

"File an issue and I'll get to it this week."

A request to turn a verbal ask into a record. It isn't a refusal — it's asking for something that can be prioritized.

"This issue has no acceptance criteria, so I can't tell where it ends."

Asking whoever filed it to write down what has to be true before it closes.

"I think this is the same as an issue that's already open."

A suggestion to merge two records of the same work.

At Pagedeck, Sofia files a lot of issues from customer email. Rather than pasting the message in, she confirms the steps to reproduce and writes those down, and that one extra step is worth about half a day of Theo hunting for the cause.

Mia reviews the list weekly to pick what goes into the sprint. Issues with empty acceptance criteria don't get picked; they go back to whoever filed them. It looks strict, but the rule appeared after a few cycles ended with someone asking whether an item was actually finished.

The most common misreading is that issues are a list of engineering work. Engineers adopted the tools first and the screen usually sits next to the code, so the impression is easy to form. But an issue is a unit of record that doesn't care about the type of work. Copy changes, research cleanup, and questions sent to an outside vendor belong in the same list, because that's the only way the team's real workload becomes visible. File only engineering work and the list looks tidy while everyone stays mysteriously busy.

Assuming that smaller is always better is the other one. Progress updates come more often, which feels like control. But file every 30-minute task and the time spent creating items and dragging them between columns starts to rival the time spent working, while the list swells to several hundred entries and buries the things that matter. The usual threshold is work one person can finish within a few days. Anything that needs to be split further goes inside the issue as a subtask.