| name | roadmap |
| description | Use when work spans weeks and the reasoning behind it is piling up — returning to a project after time away, "why did we decide X?", "where did we land on this?", "what's still open?", onboarding someone onto a long-running build, or a choice everyone remembers making and nobody can find. Not one session's state (that's `handoff`), not scoping one feature (that's `spec`). |
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.
- Destination — what done looks like, in two or three lines. What every decision is measured against.
- Decisions so far — dated, one line each, each with its why. Append-only.
- Open questions — what you can state precisely and cannot answer yet.
- Not yet specified — known unknowns, deliberately unplanned.
- 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.
Decisions are append-only
Never edit or delete a decision entry. A reversal is a new dated entry naming the one it reverses
and what changed. The excuse to catch in yourself: "the old line is wrong now, so leaving it is
misleading." It was true when it was written, and when it stopped being true is the information —
the map exists to answer "why is it like this?" nine months later, and an edited history cannot.
An index, not a store
Each entry is one line plus a pointer — to the spec, the PR, the file, the issue. Detail stays where
it already lives and stays current there. A map that reproduces content becomes a second source of
truth, and the copy is the one that goes stale (~/.mastermind/engineering/core/rigor.md refuse-list).
One open question per session
Resolve one open question per session. A session that closes five has been guessing at four. A
question leaves "Open" only when something outside the map settled it — a measurement, a call from the
user, code that now exists — and the entry that replaces it says which.
When it gets written
An entry is earned at the same moment the journal line is: the verdict closing a non-trivial task
(~/.mastermind/engineering/core/rigor.md). The journal records what happened; the map carries only
the decisions still shaping the work. Promote from the journal — never copy it across.
Map vs. handoff vs. spec
Three horizons, and the boundary is what each one outlives.
spec — one ask, decided before it's built. Retired when that thing ships.handoff — one session's live state, so a reset doesn't cost the thread. Thrown away on resume.roadmap — the project's decision history, kept for the project's life. It points at specs and
handoffs; it never absorbs them.
Gotchas
- Open it before planning, not after. Coming back cold, the reflex is to re-derive the state from
the code — which reads the what and misses every why, and reopens settled ground.
- Out-of-scope work never quietly graduates back in. Scope discipline is
rigor.md; the part that's
the map's job is that moving an item out of "Out of scope" is itself a dated decision entry — who
asked, and why now.
- Write it for someone who wasn't there. A line that only makes sense to whoever was in the session
fails at the two moments the map is for: the return after weeks away, and the new person.
