What to Write in a Task Before You Assign It to a Developer
A developer who has to guess your intent will guess in the direction that's fastest for them, not the one you meant. Here's a task structure that removes the guessing.
A task that says "fix the login bug" is not a task. It is a title pretending to be a specification. The developer who picks it up has to reconstruct everything you already know and didn't write down: which login, which bug, which browser, whether it happens for all users or just one, whether it's urgent or something to fold into the next sprint.
Every gap in that task becomes a decision the developer has to make alone. Most of the time they'll make a reasonable one. Reasonable is not the same as correct, and you won't find out which one you got until the pull request is open and the behavior doesn't match what you had in your head.
The actual job of a task description
A task description's job is not to sound thorough. Its job is to reduce the number of decisions the assignee has to guess. Every sentence you add should either remove an ambiguity or supply evidence. If a sentence does neither, it's padding, and padding hides the parts that matter.
This is a narrower standard than "be detailed." You can write four paragraphs about the history of the bug and still leave the one number the developer needs — the expected timeout value, the exact error string, the affected user ID — completely absent.
A structure that holds up under real work
This is the shape we come back to, whether the task is a bug fix, a small feature, or a change to existing behavior. Not every section is needed every time, but skipping one should be a decision, not an oversight.
- Desired outcome — what should be true when this is done, stated as a result, not a method.
- Current behavior — what actually happens right now, described precisely enough that someone unfamiliar with the system could reproduce it.
- Expected behavior — what should happen instead, in the same level of detail.
- Evidence — screenshots, error messages, logs, sample data, the exact input that triggers the problem.
- Constraints — anything that limits the solution: a library already in use, a deadline, a system this must not touch.
- Acceptance evidence — what you will look at to confirm this is actually fixed, not just believed to be fixed.
- Non-goals — what this task explicitly does not include, especially anything adjacent that someone might assume is bundled in.
The same bug, written badly and written well
Here is a task the way it usually arrives:
“Users are getting logged out randomly. Please look into it and fix.”
That's a real complaint, but it's not a task. It contains a symptom and an instruction with nothing connecting them. A developer reading it has to decide: how random is random, does this happen on mobile or desktop, is this every user or a support ticket from one person, and what counts as fixed. None of those are technical questions. They're missing information questions, and the developer will burn an hour just recovering them from Slack before writing a line of code.
Here's the same task written against the structure:
Desired outcome:
Users stay logged in for the full 14-day session unless they explicitly log out.
Current behavior:
Users on the mobile web app are logged out after roughly 20 minutes of inactivity,
even though the session cookie is set to expire in 14 days. Reported by 6 users
through support since Tuesday. Reproduces on iOS Safari; not yet confirmed on
Android Chrome.
Expected behavior:
Session should persist for 14 days across app backgrounding and device sleep,
matching desktop behavior.
Evidence:
- Support tickets #4021, #4033, #4040 (linked)
- Screen recording of the logout happening after backgrounding the app for ~20 min
- Cookie inspector screenshot showing Expires: 14 days but session invalid server-side
Constraints:
- Do not change session handling for desktop; this appears to be mobile-specific
- Must ship before Friday's release freeze
Acceptance evidence:
- Reproduce the original steps on iOS Safari, confirm session survives 20+ min background
- Confirm no regression on desktop login flow
Non-goals:
- Not addressing the separate 'remember me' checkbox request (that's its own task)
- Not investigating Android yet — separate ticket once mobile web is confirmed fixedNotice what changed. The developer no longer has to ask what "random" means, whether desktop is affected, or whether Android is in scope. Those decisions were made by the person who understood the report, before the task reached someone who didn't.
Where teams under-specify without noticing
The desired outcome and expected behavior sections are usually there in some form. The ones that quietly go missing are non-goals and acceptance evidence, and they're the two that prevent the most expensive kind of rework.
Without non-goals, a developer who sees an obviously related problem while working will often fix it too, because leaving it broken feels wrong. Sometimes that's a genuine favor. Sometimes it's an unreviewed change to something you didn't ask about, shipped in the same pull request, that nobody tested for the case you actually cared about.
Without acceptance evidence, "done" becomes a feeling instead of a check. The developer believes it's fixed because the one case they tried now works. Three days later a client hits the case nobody wrote down, and the task reopens — except now it's a different task with a different name, and the trail connecting it to the original bug is gone.
When you genuinely don't have all the sections
Sometimes you're assigning a task before you've fully diagnosed it — that's normal for a first-pass investigation. The honest move is to say so directly: "current behavior confirmed, expected behavior and root cause unknown, please investigate and report back before implementing a fix." That's a different task from a fix task, and it deserves its own acceptance evidence: a written diagnosis, not a shipped change. The failure mode isn't having gaps. It's having gaps and writing the task as if it were complete, so the developer can't tell which blanks were deliberate and which were missed.
Constraints save more time than instructions
Teams tend to over-specify the how and under-specify the boundaries. Telling a developer which function to call is often unnecessary — they'll find the right one faster than you can name it. Telling them which systems must not be touched, which library is already a dependency, or which deadline is real and which is soft, is information they usually can't get any other way. Constraints are where your organizational knowledge belongs. Implementation is where their technical judgment belongs. Mixing the two usually means you've written prescriptive instructions for the part you understand least.
Checklist tasks need the same discipline in smaller pieces
Not every unit of work is a full specification. A checklist row — "update the footer copyright year," "swap the staging API key" — doesn't need desired outcome and non-goals spelled out separately. But it still needs enough specificity that the person checking it off isn't guessing which footer or which key. If a checklist row keeps generating comment threads asking what it means, that's the signal it has outgrown a row and needs to become its own task with a real description.
In Team and Tricks, a Classic task carries a full written description alongside progress reports and time tracking, which is where this structure fits naturally. A Checklist task is for the smaller, parallel items that don't need that weight — and a row that turns out to need it can be promoted into its own Classic task rather than growing sideways inside a list it no longer belongs in.
None of this requires more time than writing a vague task and answering three follow-up questions about it later. It requires writing the follow-up questions down first, before you hand the work over, while you still remember the answers.
