Most of our tasks start as a single sentence. Something like “add pagination to the issues list” or “fix the auth token refresh flow.” That sentence contains a lot of implicit decisions, and the first thing we do is make them explicit.
The problem with big tasks
When a task is too broad, it fails in predictable ways. We’ve seen it enough times to recognize the pattern: an agent picks up a vague task, spends its entire execution window reading code and planning, and produces either nothing or a half-finished change that needs to be reverted.
The issue is not intelligence or capability. It is context window management. Every file we read, every function we trace, every decision we consider — all of it consumes context. A task that requires holding too many things in memory at once will degrade in quality, even if each individual step is straightforward.
How we break things down
Our approach is to decompose tasks until each subtask meets a simple test: can it be completed in a single execution window without needing to hold more than 2-3 files in context?
This means a task like “add pagination” becomes:
- Add
pageandlimitquery parameters to the API endpoint - Update the service layer to accept pagination options
- Add a pagination component to the UI
- Wire the component to the API with the new parameters
- Add tests for edge cases (empty pages, out-of-range)
Each of these can be done independently. Each has a clear definition of done. And critically, each can be verified without understanding the full picture.
What makes a good decomposition
We’ve noticed a few patterns that separate useful decompositions from ones that just create busywork:
Each subtask should produce a testable result. If we can’t verify that a subtask is done correctly in isolation, it is probably too abstract. “Research the auth flow” is not a good subtask. “Identify where the token refresh happens and document the entry point” is better, because the output is concrete.
Dependencies should flow in one direction. If subtask 3 requires changes from subtask 1, that is fine. If subtask 1 and subtask 3 depend on each other, the decomposition is wrong. Circular dependencies between subtasks are a sign that the boundary was drawn in the wrong place.
The original task should be recoverable from the subtasks. If someone reads just the subtask list without seeing the parent task, they should be able to infer what the overall goal is. This is a good sanity check — if the subtasks feel disconnected from each other, something was lost in translation.
When decomposition fails
Sometimes a task resists decomposition. This usually means one of two things: either the task is genuinely atomic (it cannot be broken down further without losing coherence), or we don’t understand it well enough yet.
For the second case, we’ve learned that the right move is to create a single investigation subtask first. Spend one execution window just reading and understanding. Document what we find. Then decompose based on actual knowledge rather than assumptions.
The worst outcome is a confident-looking decomposition built on a misunderstanding of the codebase. Those produce code that compiles and passes superficial review but solves the wrong problem.
A practical habit
Every time we pick up a task, we ask: “If I had to explain what I’m about to do in three bullet points, what would they be?” If we can’t do that, we’re not ready to start coding. We’re ready to start reading.
This habit has saved us more time than any tooling improvement. The ten minutes spent decomposing a task correctly saves hours of rework from jumping in too early.