The deep dive · chapter 6 · 7 steps

Ideas that don't evaporate

Capturing a suggestion in one move, the six lines that make it decidable, and the design choice that stops the list rotting.

1. The problem — the good idea from Tuesday
Somebody said something genuinely useful in a conversation on Tuesday. By Thursday nobody can reconstruct it, including them.

Every team knows the fix is "write it down somewhere", and every team has a somewhere that nobody reads. Idea lists fail for two specific reasons, and they're worth naming because the design here is aimed at both.

Capture costs too much. If recording an idea means opening a tool, choosing a category, estimating effort and picking a priority, you won't do it while you're in the middle of something else — which is exactly when the idea arrives.

The list only grows. A list of ninety items with no decisions attached is the same as no list, except it also makes you feel bad.
2. Five folders, and that's the design
A folder is the status
aidlc — zsh
$ ls .aidlc/roadmap/ inbox/ somebody suggested it backlog/ we agreed to do it in-progress/ work has started done/ shipped hold/ not now
the whole design
There is no "status:" field anywhere in an idea file. Two places recording one fact eventually disagree, and a wrong status looks exactly like a right one.
step 1 of 3
Read the first frame again, because it's the whole thing: the folder an idea sits in tells you its status. There is no status: field in an idea file, and adding one is explicitly forbidden.

That sounds like a stylistic preference. It isn't. Two records of one fact eventually disagree, and when they do, a wrong status looks exactly like a right one — nothing reports it, and you find out when somebody works from the stale one. Moving the file makes disagreement impossible rather than merely unlikely.

The five folders are inbox (somebody suggested it), backlog (we agreed to do it), in-progress (work has started), done (shipped), and hold (not now, or no).

hold deliberately holds both "parked" and "declined", so one folder serves both. What tells them apart is the reason on the item's history line: a move into hold/ carries a reason that starts parked — or declined — . Agreed work that is waiting on something goes there as parked, not in backlog/, because backlog/ means "could start now". From a running piece of work, aidlc roadmap park does the move and writes the parked — reason for you.
3. The six lines
Every idea opens with a summary of exactly six labelled lines: what it is, who benefits, what they can do afterwards, whether it makes money, rough cost and the main risk, and a recommendation.

Six, and no more. The purpose is that a decision can be made from the top of the file. An idea whose value cannot be stated in six lines is one nobody can decide about, so it sits there while everyone waits for somebody else to read the whole thing.

Two of the rules attached to it are more interesting than they look.

"None" is a real answer for revenue, and often the right one. In the frame above, an alert email earns nothing directly, so the line says None and says why. Writing "indirect" for everything makes the field useless — and worse than blank, because it reads as answered. It's also the cheapest available honesty check: an idea that has to write revenue — none and value — it observes the process rather than serving a user has just declared itself.

Write it last. A summary drafted before the detail is a guess wearing a summary's clothes.
4. Your turn
your turn · Agree to do something
An idea has been sitting in the inbox and you have decided you want it. How do you change its status to "agreed"?
```
$ the command that changes the status

$ ls .aidlc/roadmap/backlog/
20260902-price-alerts.md
```
Which line goes in the blank?
This exercise needs JavaScript. The transcript above is complete apart from the blank.
5. Choosing and starting the next one
Three read-and-rank commands answer "what should we do next?" without anybody having to remember.
```
aidlc roadmap next
aidlc roadmap next --explain
```
The first names the backlog item with the lowest rank whose dependencies are done. --explain shows the whole ready order and anything it skipped, with the reason. Neither one writes anything. Picking is deterministic; promoting stays your decision.

To change the order, give an item a rank:
```
aidlc roadmap rank 20260902-csv-export 1 --dry-run
```
Run it with --dry-run first. It prints the order you would get and writes nothing:
```
dry run — nothing written; 20260902-csv-export.md would be ranked 1
  > 1  20260902-csv-export.md — Export watched prices to CSV
    2  20260902-price-alerts.md — Alert me when a price drops
    3  20260902-dark-mode.md — Dark mode for the dashboard
```
Then run it again without the flag. Every other rank is renumbered, so ranks stay unique with no gaps. Don't type priority: by hand. (Ranking needs the project to declare a priority field for its roadmap items.)

To see everything at once:
```
aidlc roadmap view --no-open
```
That writes one HTML page, a board by status plus a map of which items wait on which. Leave out --no-open and it opens in your browser.

Promotion is where the list meets everything in the earlier chapters: pick a workflow, pick how far back to start, create the work, and let the idea seed it. It is one command:
```
aidlc start full-feature --name price-alerts --roadmap-item 20260902-price-alerts
```
The third frame shows it. The command creates the work, sets promoted_to on the idea, moves the file to in-progress/ and copies it into the work as its starting point. If anything fails part way, it removes what it made and leaves the idea where it was. The move is left uncommitted; committing it is yours.

Don't do those steps by hand with git mv. Two unattended runs of the hand-made version once disagreed: one linked the idea, the other left it in backlog/ with no link, so the idea would never have reached done/. When the work finishes, the idea moves to done on its own. The completion event does it, which is the only reason it reliably happens.

Autopilot works this same backlog in the background while you do something else. The recipe is let autopilot work the backlog.
6. The cap, and why it's uncomfortable
The rule this project ended up needing: cap the list at around a dozen raw ideas. At the cap, promote something or drop something before capturing anything new.

That's unpleasant, and it's the point. An idea list that only grows is a list nobody triages. Forcing a decision at capture time means the decisions actually get made, and the ones you drop were mostly going to be dropped in eighteen months anyway, having taken up room the whole time.

There's a related discipline about follow-ups. Every finished piece of work generates suggestions for next time, and the default for those is dropped — keeping one requires a stated reason. Finishing work reliably generates more work than it retires, and if you keep every follow-up the list becomes a machine for creating work about work.

The one exception is worth knowing, because this project paid for it: if a fix is understood well enough to write down in prose, capture it as an idea in the same breath. A follow-up described in a completion note here was rediscovered from scratch three days later, re-analysed, and re-scoped as new work. Prose is not a work item.
7. What you can do now
You can capture an idea mid-task in one file with no ceremony, decide on somebody else's idea by reading six lines, and change its status by moving it. You can ask what's next, change the order with aidlc roadmap rank, look at the whole roadmap with aidlc roadmap view, and turn an idea into work with aidlc start --roadmap-item. And you know why there's no status field to edit.

Next: what actually breaks when two people work in the same folder at the same time. It isn't what you'd expect.

Kept in this browser only. Nothing is sent anywhere.

Ideas that don't evaporate

1. The problem — the good idea from Tuesday

2. Five folders, and that's the design

3. The six lines

4. Your turn

5. Choosing and starting the next one

6. The cap, and why it's uncomfortable

7. What you can do now