The roadmap layer

The roadmap is the top of the two layers from A1.04: it answers how we deliver — the milestones, the iterations, the Author/Operator loop — as a coarse, ordered sequence of rungs. Each rung on the roadmap is a one-line intent plus a definition of done: “a branded id; done = it decodes to its type.” That is all. The behaviour — the contract, the fields, how it is proven — lives one layer down, in the spec, authored later when the rung is sharpened (A1.03.2).

So the roadmap points at the specs; it never holds them. A roadmap item says when and whether a rung is taken; the spec says what it does and how it is proven. Put behaviour into the roadmap and it stops being a plan: it becomes a frozen, up-front specification of everything at once — the big-bang spec (A1.01.2). The whole value of the layer is that it stays coarse.

A roadmap holds no behaviour, so re-ordering it costs nothing. Promote a rung, drop one, split another, and not a single spec changes — because the specs are not in the order, they are pointed at by it. That is the point of the layer: delivery can adapt to what the loop learns without disturbing the definition of any rung. The moment the roadmap carries the behaviour itself, that cheap re-planning is gone.

The line is the granularity. A roadmap rung is coarse on purpose — one line and a tick — and a coarse rung is a pointer you can move. Cram the full behaviour spec into that same slot and the slot is no longer a plan you re-order; it is a contract you would have to re-negotiate to move. Switch the rendering below to see one rung at each granularity, and which one a roadmap is allowed to hold.

The Portal roadmap — the learning platform this course builds — is a sequence: a branded id, then storing one event, then one read model, then a Telegram command, then the dashboard. Each is one line plus a definition of done — “an id that decodes to its type” — not a spec. The id's behaviour lives in its spec, never in the order.

As the loop runs, the order is re-planned. If the dashboard rung turns out to depend on the read model, the read model is promoted ahead of it: the order changes, and no spec is touched. The plan adapts to what the Portal taught; the definitions of the rungs do not move with it.

# The Portal roadmap — order only; each rung is a line + a definition of done, never a spec.
roadmap = [
  "branded id",        # done: decodes to its type
  "store one event",   # done: appended & replayable
  "one read model",    # done: projects the count
  "telegram command",  # done: replies to /start
  "dashboard"          # done: renders the model
]

# Re-plan: promote a dependency. The order moves; not one spec does.
roadmap = List.delete(roadmap, "one read model") |> List.insert_at(3, "one read model")

# The behaviour of a rung is pointed at, not held: it lives in the spec layer.
#   id = Portal.ID.generate(:user)  ·  Portal.ID.decode(id).type == :user   (A1.04.2)

The roadmap layer answers how we deliver: a coarse, ordered sequence of rungs, each a one-line intent plus a definition of done. It points at the specs and never holds them, so re-ordering it is free — promote, drop, or split a rung and no spec moves. The one failure to avoid is behaviour creeping into the order, which turns the plan back into the big-bang spec. With the order settled, the next dive opens the layer below, where the behaviour of each rung is actually written.

Primary sources for ordered, re-plannable delivery, and where the roadmap layer connects in the course.