kaizen-agentic/context/KeepaTodofile.md

keep a todofile

Don't let your mind or coding agent loose context and mess up your coding flow.

Version 0.0.1

# Todofile

This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.
                                                                                                                                           
The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).

The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.

***

## Keep a TODO Manifest Structure (TODO.md)

The document should always have an **Unreleased** section for immediate, in-progress, or newly discovered tasks, and then ordered sections for future planned versions.

### **\[Unreleased\]** - *Active Vibe-Coding State* 💡

This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.

* **To Add:**
    * Implement the `getUserProfile()` function in the `data-service.js` file.
    * Add a temporary mock data endpoint for the dashboard widget.
* **To Refactor:**
    * Change the variable name `d` to `dataObject` in the primary API handler.
* **To Fix:**
    * The `LoginButton` component flashes briefly on mount due to missing key prop.
* **To Remove:**
    * Delete the unused `legacy-utils.ts` file before committing.

***

## **\[0.1.0\] - Short-Term Feature Commit** - *First Planned Increment*

This version represents the first set of concrete, planned features and cleanup tasks you aim to complete before the next logical interruption or commit boundary.

### **To Add**
* Implement **User Authentication** via basic email/password (stubbed out for now).
* Create the initial **Dashboard View** with three empty placeholder widgets.
* Add **Input Validation** library (`yup` or similar) to the project dependencies.

### **To Refactor**
* Migrate all configuration constants from inline code to a central **`config.json`** file.
* Rename the core service class from `CoreLogic` to **`TaskProcessor`** for better clarity.

### **To Fix**
* Resolve the **environment variable loading issue** that prevents the database connection from starting in development mode.
* Ensure that all API responses correctly use a **snake\_case** naming convention for JSON keys, not camelCase.

### **To Deprecate**
* Plan to remove the older **`POST /api/v0/task`** endpoint entirely in version 0.2.0, in favor of the new, more flexible `POST /api/v1/tasks` endpoint.

### **To Secure**
* Set up a basic **CORS configuration** to allow requests only from `localhost:3000`.

### **To Remove**
* Delete the boilerplate **README.md** content and replace it with project-specific documentation and setup instructions.

What is a todofile?

A simple, usually plain text or Markdown file (TODO.md), located within a project's source code, that explicitly lists uncompleted tasks, required fixes, refactorings, and next steps for the current development effort.

Why keep a todofile?

To offload mental state, maintain focus during coding flow ("vibe coding"), and create a single, shared, immediately accessible source of truth for both the human coder and any coding assistant regarding the project's most immediate and granular future state.

Who needs a todofile?

The individual developer (especially when working alone or in short, intense sessions) and, critically in the modern workflow, any AI coding assistant that needs to maintain context and contribute to the immediate, next-step plan.

How do I make a good todofile?

Guiding Principles

• For Humans & AI: The TODO.md is the single source of truth for the current development state and immediate next steps.
• Track by Impact: Group future tasks by the nature of the change they will introduce (e.g., To Add, To Fix, To Refactor).
• Context over Content: Use in-code // TODO: comments for highly specific, localized reminders.
• Offload the Brain: Use the manifest to capture every thought, ensuring nothing is lost during an interruption.
• Offload the Manifest: Keep your coding session bounded. Instead of following sidetracks immediately create issues.
• Maintain the Untracked: Always keep an [Untracked] section for tasks that are actively in progress or discovered during the current coding session.
• Version the Plan: Organize future steps into planned versions (e.g., [0.2.0]) to create clear commit boundaries using issues.

Types of Todos

• Added for new features.
• Changed for changes in existing functionality.
• Deprecated for soon-to-be removed features.
• Removed for now removed features.
• Fixed for any bug fixes.
• Security in case of vulnerabilities.

How can I reduce the effort required to maintain a todofile?

Use In-Code TODO Comments: Use standard comments (e.g., // TODO:, # FIXME:) for specific, localized, and temporary tasks. This eliminates context switching and places the task exactly where the work needs to be done.

Leverage IDE/Tooling: Use editor extensions (like VS Code's "Todo Tree") that automatically scan and consolidate these in-code comments into a single navigable list, effectively turning scattered notes into a central manifest without manual copy-pasting.

Maintain Only the Immediate: Keep the dedicated TODO.md file focused primarily on the [Unreleased] section, covering only the highest-level tasks or the immediate "next steps." Once a major feature is complete, delete the related tasks rather than moving them elsewhere.

Delegate to the AI Assistant: Explicitly instruct your coding assistant to read, update, and resolve items in the TODO.md file. By making the file the single source of truth, you pass the maintenance burden of tracking state to the tool.

Keep Format Minimal: Stick to a simple Markdown checklist format. Avoid complex tooling (like a separate issue tracker for short-term tasks) that requires external steps or login credentials.

Can todofiles be bad?

Yes. Here are a few ways they can be less than useful. The goal of a maintaining a TODO.md is to foster flow, but several common mistakes turn it into a source of friction and "technical debt." Here are common anti-patterns that hinder more than help with todofiles:

1. The Invisible Backlog (The Graveyard)

• Antipattern: Committing a massive number of unaddressed // TODO: comments into the main codebase.
• Hinderance: These scattered, unprioritized items form an "invisible backlog" that no one actively manages. They quickly become stale, confusing, and are rarely addressed, leading to developers ignoring all TODO comments.

2. Vague or Contextless Tasks

• Antipattern: Writing ambiguous entries that lack context.
• Example in Code: // TODO: fix this later
• Example in File: - [ ] Dashboard data
• Hinderance: When you return after an interruption (or a few days), you and the AI assistant have to spend time deciphering what the original problem was, defeating the purpose of offloading memory.

3. The Duplicated Tracker

• Antipattern: Maintaining a long, detailed list of tasks in the TODO.md that exactly mirrors an external system (like Gitea, Jira, Trello, or GitHub Issues).
• Hinderance: This creates maintenance overhead. The two lists inevitably drift out of sync, leading to confusion about which is the source of truth, and wasting time copying and pasting between systems.

4. Long-Term Planning in the Flow Tool

• Antipattern: Using the immediate TODO.md manifest to plan work that is months away or requires product management sign-off (e.g., v3.0 features).
• Hinderance: The document becomes cluttered, making it difficult to see the genuinely urgent and immediate next steps. The focus tool is turned into a long-term project planning tool, which it is ill-suited for.

5. Poorly Defined Boundaries

• Antipattern: Not clearly differentiating between the two types of tasks:
• Flow State: The temporary // TODO: comment that should be resolved before the current feature is considered "done."
• Commit Boundary: The high-level task in TODO.md that marks the next logical piece of work.
• Hinderance: The coder struggles to know when a task should be moved, deleted, or transferred to the formal issue tracker, leading to tasks getting stuck in the TODO.md limbo.

There's more: Help me collect these antipatterns by opening an issue or a pull request.

TODO: setup keep-a-todofile as a repo with proper domain and issue tracking.

Frequently Asked Questions

Is there a standard todofile format?

There is no official standard, but the common and most effective format is a simple Markdown checklist (using [ ] for pending and [x] for complete), often organized by category (e.g., To Fix, To Add, To Refactor) and version.

What should the todofile be named?

Common and recognizable names are TODO.md or NEXT.md (or .txt). Using a simple name with the .md extension ensures it's easily read, recognized by IDEs, and accessible to coding assistants for context.

When should the todofile be pruned and rewritten?

The TODO.md should be pruned (removing or transferring resolved items) and potentially rewritten at the end of a coding session when commiting to the repo. At the latest it needs to be updated when merging the current branch or finishing major feature implementation, before a significant commit/merge (e.g., to main), or when starting a new major version increment (e.g., moving from v0.1.0 to v0.2.0).

How can I contribute?

This document is not the truth; it’s my carefully considered opinion, along with information and examples I gathered.

This is because I want our community to reach a consensus. I believe the discussion is as important as the end result.

So please pitch in.

TODO: setup zulip space to collect feedback and improvements.

Conversations

Discussions and ideas round and about CoulombSocial spiked this manifest. Let's keep integrating and refining to make this useful as can be. Feel free to check out how to cocreate and engage with the community there.

Kudos

Thanks to Oliver Lacan for providing the inspiriation to try and establish a baseline for staying on track with a todofile. I hope some of us will find it useful.

This manifest adapts the excellent principles of keepachangelog.com for maintaining a shared mental model in a fast-paced coding session. If you "Keep a TODO Manifest" (let's call it TODO.md), you establish a clear, structured shortterm plan that both the human coder and the coding assistant can use as the single source of truth for what to do next.