Write Down TODOs

Write Down TODOs

Intent

Don't try to solve everything at once. Record an open issue and return to it later.

Introduction

“There’s always more work you can do” is a truism in software engineering, but you don’t need to do all of that work right now. Piling multiple, unrelated or vaguely related, tasks into a single coding session is exhausting and demotivating for the programmer, and causes context and attention problems for the coding assistant. Instead, keep track of items you need to do, but can defer for later. Store their descriptions somewhere you can come back to, but that your coding assistant won’t automatically load into context.

Problem

Completing work has a frustrating habit of generating more work. Whether you discover bugs caused by integrating a new feature into the system, opportunities to improve quality, new design questions motivated by designing your current task, security or performance problems, or something else, the reward for getting something done always seems to be a chance to do something else.

Attempting to address all of these problems as they arise, in a single session with a coding assistant, introduces multiple issues. The LLM needs to track these different problems, along with the code and text it generates in response to them, in its context. This leads to multiple, loosely-related ideas in its context that can dilute or misdirect the attention layer, so that the model generates incorrect solutions as the problem space grows.

The situation causes you problems, too. Considering so many different problems in a short space of time can lead to fatigue or burn-out. It might also be demoralising, when you believe that your session isn’t over until each one of these problems on the growing list is addressed and mitigated.

Solution

Keep track of the issues you identify, but evaluate their priority and come back to each only when you determine that it is the most important next task. You may find that some tasks are necessary to close out your current work with your assistant, or are more urgent than your current work—these are the only ones you should address immediately. Record everything else, in a task database if possible, and come back to it later. The tasks you record for later can come from a need to Defer the Details on your current activity, or other issues that you observe while you work with your assistant.

Recording these tasks as TODOs ensures that you don’t lose track of them, and means that they don’t block completion of your current task. Information about those tasks doesn’t fill your assistant’s model context and dilute the attention it pays to your current task.

Additionally, you get to work at a sustainable pace, completing important tasks when you need to and deferring other issues to address later, or to abandon if they turn out to be unimportant.

Applicability

Use Write Down TODOs at any stage in software development. When you’re planning a system, identify the most important behavior to satisfy the customer’s needs—or to validate whether customers even have the problem you hypothesize—and Write Down TODOs for other features.

As you build out that first feature, build a spike or tracer bullet that uncovers the important attributes of the problem domain and your solution, and Write Down TODOs for anything else.

During coding, focus on your task and Write Down TODOs for unrelated issues you observe, where they’re less urgent than completing the current task. For example, during a refactoring activity, Write Down TODOs for behavioral changes you might want to make.

If You Review your assistant’s plan for generating a fix for your prompted problem and not all of the steps are immediately necessary, Defer the Details—a specific example of Write Down TODOs.

Write Down TODOs is a useful follow-on pattern when you Disclose Ambiguity, if the assistant identifies an open question in your problem statement that doesn’t need an immediate answer.

Considerations

Write Down TODOs offers the following benefits:

• Focus on what’s actually important.
• Avoid diluting the model’s attention by changing tasks mid-session.
• Keep track of what you still need to do.

You have to consider the following concerns when you apply the pattern:

• Systematically record TODOs to avoid duplication, or creating additional work interpreting your records.
• Keep your records up-to-date, and remove any TODOs that become irrelevant or unimportant.

Implementation

When you identify something that you might need to do, or a problem that you might need to fix, but that you don’t need to address now, prompt the assistant to write the description of that task for later.

You can also Intervene to tell your assistant to Write Down TODOs for a task it’s started on, that you don’t need to complete yet.

You need to record the task somewhere that’s visible, so you remember to come back to it later. You also need the task’s description to stay out of the way until you work on that task, so that the model doesn’t load the description into context any time it reads information about other, unrelated tasks.

A task tracker, for example beads, represents a good choice. The task titles remain available for you and the assistant to browse, and the tool automatically filters out tasks that are complete, or blocked by other work. When the assistant picks up a task, it can fetch the detailed description of the task into context.

A less appropriate venue for TODOs is in source code comments. While in-source TODOs have the benefit that you see them whenever you work on the source, that benefit presents a drawback for LLM-based coding assistants because the assistant loads the task descriptions into context whenever it reads the source file, even if you’re working on an unrelated task.

Examples

We Don’t Need a UI Yet

I used Gemini 3.1 Thinking in the Antigravity IDE to plan a tool for improving data visualization in software development. I described my problem statement at a high level, and asked Gemini to Disclose Ambiguity to understand what I needed to specify before I could generate a prototype solution. It generated three questions:

To differentiate your tool from the 2026 "standard," I need to understand the **Core Differentiator** of your system. Please describe your target system, focusing on these three areas:

1. **The "Hook"**: What is the one thing your tool does that makes a developer say, _"I can't believe I used to do this manually"_? (e.g., Is it a new way of visualizing state? A unique "Human-in-the-loop" feedback mechanism? A focus on legacy migration?)

2. **The Interface**: Is this a standalone IDE, a CLI-first agent, a browser-based "Canvas," or a background service that sits on top of existing tools?

3. The Scope of Autonomy: Does it just write code, or does it own the full SDLC (Planning -> Coding -> Testing -> Ops)?

My response to the question on the interface was to Write Down TODOs to create a spike to explore the UI, prompting the assistant to focus on defining the core features for the prototype:

2: I’m not sure we need to define that yet? We need to define the epics/stories and can leave implementation questions to an architectural spike. Add a task to explore the UI and then return to refining the traceability requirements.

Waiting to Fix a Language Bug

I used Claude Sonnet 4.6 in Claude Code to port some code in an existing Objective-C project to my AppScript interpreted language, to enable faster iteration while exploring the app’s requirements. In completing the port, the assistant discovered a bug in the interpreter—it uses metadata to create a synthesized class that exposes functions and constants defined by a system framework, but then doesn’t discover that synthesized class when a script calls it by name.

While the assistant pursued that error, I noticed that there was a workaround where it could use system APIs in a different way so that it doesn't need to call the function. I Intervene, confirm that the workaround works, then Write Down TODOs to fix the interpreter problem:

Can you add a task to beads to ensure the BridgeSupport classes are available in AppScript, as the whole point of the BridgeSupport feature is to make those functions available to the interpreter.

Created asu-7fe — "Make BridgeSupport proxy classes accessible in AppScript interpreter".
The description captures the root cause: ASBridgeSupportInstaller registers the proxy
classes with the ObjC runtime but the interpreter's identifier resolver doesn't fall back
to NSClassFromString, so [ASAppKit NSZeroRect] and similar patterns fail. The fix belongs
in the interpreter's lookup path.

Related Patterns

Defer the Details when you discover that the current task is really a collection of small tasks, not all of which are urgent.

Clean Slate between the current task and the TODO you come back to.

Take Baby Steps, and Write Down TODOs for the steps that you don't need to complete right now.