roadmap

MasterMind: Map

Long work loses its reasoning long before it loses its code. Six sessions in, the why behind a choice is gone, and the seventh session relitigates it, or silently undoes it. This is the one artifact that outlives the sessions: a decision map the project owns and appends to for the life of the work.

The file: five sections

.mastermind/MAP.md, one per project. Nothing that isn't one of these five belongs in it.

1. Destination: what done looks like, in two or three lines. What every decision is measured against.
2. Decisions so far: dated, one line each, each with its why. Append-only.
3. Open questions: what you can state precisely and cannot answer yet.
4. Not yet specified: known unknowns, deliberately unplanned.
5. Out of scope: and what it would take to change that.

A decision entry, and the reversal of one, look like this:

2026-03-04 · Sessions live in Postgres, not Redis: one datastore to operate, and
             nothing needed sub-millisecond reads. → specs/auth.md
2026-05-19 · REVERSES 2026-03-04: sessions move to Redis. The read path became the
             p99 at 340ms once org switching landed. The original reason still held;
             the traffic changed. → PR #412

Only section 2 is append-only. The other four describe the present and get rewritten freely: a resolved question leaves "Open questions" the moment it becomes a decision.

Fog of war: don't chart what you can't see

The test for "Open questions" is whether you can state the question precisely today, not whether you can answer it. "Which queue runs the nightly export?" is an open question. "How does billing work?" isn't a question yet; it's a region of fog.

Write the fog as one line naming the unknown and what will lift it: "Billing model, unspecified until the pilot returns pricing feedback." That line is the whole entry. A map carrying a plausible plan for month three reads as decided, and the next session builds against something nobody ever chose.