A Roadmap Is a Working Surface

I opened a project roadmap and found a milestone marked “M2 complete.” The label did not tell me what had shipped, which behavior demonstrated it, or why the next task was a retrieval guard instead of an email invite.

That is too little state for a small team moving quickly, especially when AI coding sessions hand work to one another. The roadmap has to be a working surface that changes with the implementation.

It says:

1. Here is what we believe is done.
2. Here is what is in progress.
3. Here is what is blocked.
4. Here is what changed since the last time we looked.

Those four lines are more useful than a confident quarter-by-quarter deck when someone needs to resume the work on Monday morning.

The roadmap should sit next to the work

I keep roadmap state close to the build context. A planning tool nobody opens while coding and a chat thread that disappears under newer messages both make re-entry harder.

The roadmap must be close enough that an implementation agent, a reviewer, or a tired human can answer practical questions without reconstructing the whole project:

• What is already complete?
• What milestone does this task belong to?
• What is the next sensible task?
• What infrastructure is assumed to be running?
• What command verifies the work?

These details sound too tactical for a roadmap. I think that is exactly why they belong there. A roadmap that cannot guide the next hour of work is only partially useful.

Milestones need evidence

"M2 complete" is not evidence.

It is a label. Evidence looks more like:

CSRF flow implemented.

Join-code rotation completed.

RAG orchestrator is next.

Public auth and throttling remain after that.

Local Postgres is on this port.

Tests run with this settings module.

The difference is important. Labels make progress feel tidy. Evidence makes progress transferable.

When someone new enters the project, including a future version of yourself, they do not need confidence theater. They need enough concrete state to avoid repeating discovery work.

That is especially true in agent-assisted development. Agents are good at moving quickly once context is clear. They are also very good at wasting time if the project state is vague.

A roadmap should reduce the cost of re-entry and show enough recent history to explain the next move.

Building with AI: Separate coding sessions can each report a task complete while the consumer-facing feature remains unfinished. I still choose the milestone boundaries and review the shared state; AI handles much of the implementation. A completion claim now needs observable evidence, the current consumer state, and the next constraint in the same roadmap entry.

Backlog stores options; the roadmap chooses

The backlog stores possible work. The roadmap chooses the current path through it.

If the next task is "build retrieval and orchestrator guards", say that. If email invites are 40 percent done but not the next constraint, say that too. If backend milestones are ahead of frontend integration, make the mismatch visible.

The useful part is making the next decision easier:

1. What should happen next?
2. What should not happen yet?
3. What should be preserved because another piece depends on it?

The artifact should be allowed to change

Whenever I am building features or products, I see roadmaps fail when changing them feels like admitting failure.

In real projects, discovering the work changes the work. A milestone that looked independent turns out to depend on auth. A public endpoint needs throttling before it should be exposed. A design task reveals an architecture decision.

Discovery changed the roadmap because the earlier plan did not yet contain those facts.

The important thing is to update it while the discovery is fresh. If the roadmap lags behind the work, it becomes another stale document people have to mentally correct.

Stale roadmaps are worse than no roadmaps because they create false orientation.

A good roadmap lowers coordination cost

A roadmap coordinates present attention with past decisions.

For a builder, it coordinates present attention with past decisions. For a team, it coordinates parallel work. For a swarm of agents, it coordinates context across sessions. And for reviewers, it coordinates the diff with product direction.

The roadmap is doing its job when fewer people have to ask:

Wait, where are we?

It is doing its job when the next task is obvious enough to begin, and the current state is concrete enough to challenge. That second part matters. A roadmap should not be vague enough that it cannot be wrong.

If it says the system has public auth, someone should be able to point to the implementation. If it says a milestone is complete, the verification path should be visible. If it says a task is next, the reason should survive a morning of scrutiny.

A roadmap entry I can resume

A useful entry is small enough to keep current and concrete enough to challenge:

### Knowledge ingestion — in progress

Shipped:
- URL and pasted-text sources enter the same fact pipeline.
- Detected facts retain source provenance.

Observed:
- A crawled page creates source-linked facts.
- An edited fact survives a later crawl.
- The dashboard displays the same source shape returned by the API.

Next:
- Add answer-aware dedup before enabling recrawl by default.

Consumer handoff:
- Frontend must regenerate schema and render `detected_from` as an object.

This is a deliberately narrow project record: behavior, evidence, next constraint, and consumer obligation.

The result is shorter re-entry. A builder can continue from the artifact instead of replaying chat history or trusting “M2 complete.” I no longer move a milestone to complete until the observable behavior and consumer state are recorded beside it.