mehrad-dm 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.
interview: 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.