Why the file exists
Work turns things up. A permission nobody grants, a screen that loads records it never shows, a defect sitting beside the one you reported. None of it belongs in the task that found it — a run that widens its own scope is a run nobody agreed to — so the command names it at the end of its report and moves on.
A report is gone when the conversation ends. So what a command noticed is also written into todos.md, a document of your project in the toolkit, beside the analysis folder. You read it in the Projects section; it is not a file in your repository. When nothing urgent is left, that one file tells you what is actually worth doing next.
There is one per project, never one per module, and it is written in your language. The first command with something to write creates it.
It is a list, not a plan
A row says what is wrong and where. Deciding what to do about it is the planning step's, and building it is the build step's. When you ask /plan-prompt for something that matches a row, it reads the file and treats your request as that row being taken up rather than as new work.
What a row looks like
The file has three sections, in this order: High, Medium and Low. Each row carries five things:
- The area of the product, in bold — the one a person would name, like Billing or Admin.
- What is wrong, in one or two plain sentences, naming the screen, the flow or the record, so somebody who was not there can judge whether it matters.
- Where it was found — the work that turned it up.
- The date.
- The command that wrote it.
Nothing else: no status, no owner, no estimate. A row that needs any of those has stopped being a finding and wants a plan.
Which section it goes in
Priority is about what it costs to leave alone, never about how hard it looks to fix.
- High — someone loses data, sees something they should not, or cannot finish a thing the product promises. Also anything that gets worse as records or users grow.
- Medium — it works, but wrongly or wastefully, in a way a person would notice: a slow screen, a rule applied in one place and not its twin.
- Low — nothing is broken today: dead configuration, an unused permission, a duplication that has not caused a defect yet.
When two readings are arguable, the lower one wins. A list where everything is High sorts nothing.
What gets written, and what does not
Only what is close to the work that found it — the same files, screens or flows the task already touched. Something noticed during a detour into an unrelated area is dropped: a finding with no context around it is one nobody can act on.
Three things never become a row:
- A defect in the task's own work. Wrong behavior on the screen or flow the task is building, checking or documenting is corrected in the same run, not left for later.
- A decision. A row says what is wrong; it never asks anybody to choose. What only you can settle is asked as a question — of the plan, when there is one — or named in the report.
- Code another repository owns. It goes to that repository as a request, as Send a defect to the repository that owns it explains.
The same finding turning up again is not a new row; the one already there is left as it is. Before a row is saved, the command that writes it checks that it carries the five parts above and sits in the right section.
Writing a row is not an invitation to investigate it. What goes in is what was noticed, at the cost it was noticed for.
Who adds a row, and who takes it out
Any command that finds something close to its work adds the row. One that only reports never removes any. One that writes no document — the browser check /test, for example — writes no row either: it hands its rows to whoever called it, so the run that acts on a finding is the one that records it.
Whoever fixes it takes the row out, in the same run as the fix, whether the fix was planned from this list or happened to pass through. A row is removed only when the run can say what it changed that makes the row untrue; when it cannot without going to look, the row stays and the report says so.
Nothing else removes a row on its own. No command prunes rows it did not fix, ages them out, or rewrites somebody else's wording. A finding nobody has fixed is still true, however old it is.
You can. Ask any command, /cloud-doc included, to add, change or remove a row and it does — a row you ask for keeps the same five parts. Or open todos.md in Your projects and their documents and edit it by hand.
Next
- Planning before building — what happens when you take a row up.
- Run the queue with /next — working through the plans that come out of it.
- What the analyzer cannot check — the other kind of thing a person has to look at.