Six weeks into your project, someone in the team chat asks: "Wait, why doesn't the player have a jump?" And the whole thing starts again. Two people re-argue it from scratch, a third says they thought it was still open, and the person who originally made the call is on holiday. You lose an afternoon, and nothing about the game changed.
That is the cost of undocumented decisions, and it compounds. Every design choice you make quietly creates a dozen downstream assumptions — in level layouts, in animation budgets, in the combat spreadsheet. When the choice itself is invisible, the assumptions get re-examined every time someone new touches the file.
The fix is unglamorous and takes about four minutes per decision: a decision log.
What a decision log actually is
A decision log is a chronological list of design and technical calls your team has made, each recorded with the reasoning and the alternatives you rejected. It is not a spec, not a task board, and not a GDD chapter. Those describe what the game is. A decision log describes why it is that way.
The distinction matters, because the "why" is the part that decays fastest. Your GDD will say "the player has no jump; traversal is handled by mantling and vaulting." That is useful. But it does not tell the new level designer in month five that you cut jumping because your collision setup produced unfixable ledge-clipping on curved geometry, and that mantling was the second choice after a grappling hook that broke your encounter pacing. Without that, they will propose the grappling hook again. Probably twice.
Software teams have used this pattern for years under the name Architecture Decision Records (ADRs), popularised by Michael Nygard around 2011. Game teams need it more, not less, because game design decisions are less falsifiable — you cannot prove a jump was wrong the way you can prove a race condition was wrong, so the argument never fully closes on its own.
The five fields that do all the work
Keep the format small enough that people actually fill it in. Five fields is the sweet spot:
| Field | What goes in it | Length |
|---|---|---|
| Title | The decision as a statement, not a question. "No jump button; traversal via mantle + vault." | One line |
| Status | Proposed, Accepted, Superseded (by #ID), or Reversed | One word |
| Context | What forced the decision — the constraint, the playtest result, the deadline | 2–5 sentences |
| Decision | What you're doing, specifically enough to build from | 1–3 sentences |
| Alternatives rejected | What else you considered and the reason each lost | Bullets |
The last field is the one teams skip and the one that pays for the whole system. "Alternatives rejected" is what stops the re-litigation, because it lets someone check in ten seconds whether their new idea is actually new.
A filled-in example:
DL-032 — Enemy health scales with encounter count, not player level Status: Accepted (2026-04-11) Context: Playtest 7 showed three of five testers grinding low-level enemies before the mine, which made the mine trivial and the boss unreadably hard. Level-based scaling was masking our tuning problems rather than solving them. Decision: Enemy HP and damage are fixed per encounter, authored by hand in the balance sheet. Encounters are tuned against the expected loadout at that point in the critical path. Alternatives rejected:
- Level-based scaling — hides tuning errors, and testers reported that enemies "felt like they were cheating."
- Soft scaling with a ±15% band — same problem, extra complexity, and no tester in P7 noticed the band existed.
- No scaling but gate progression on gear — pushes the problem into the loot table, which is less stable than the encounter list.
Notice that the whole entry is about 130 words. That is the target. If an entry needs 600 words, it is probably three decisions.
When to log, and when not to
Logging everything is as useless as logging nothing — a log with 400 entries has the same searchability as no log at all. Use a threshold. Log a decision if any two of these are true:
- It took more than 20 minutes of discussion.
- It closes off a direction someone might reasonably want to reopen.
- It constrains work in another discipline (art, audio, engineering, narrative).
- It reverses something you previously shipped or documented.
- It came out of playtest data you'd otherwise have to re-run to justify.
- Someone outside the room will have to live with it.
Things that do not need a decision log entry: which font the damage numbers use (unless you fought about it), the exact value of a tuning constant that lives in a spreadsheet anyway, or anything a task board comment already captures adequately.
Roughly, a three-person team on a two-year project should expect somewhere between 60 and 150 entries. If you are logging more than one a day, loosen the threshold.
Statuses: never delete, always supersede
The single rule that keeps a log trustworthy is that entries are append-only. When you change your mind, you do not edit DL-032 — you write DL-089, mark DL-032 as Superseded by DL-089, and in DL-089's context field you say what changed.
This gives you something no wiki page can: a readable history of how the design moved. Six months later you can see that you tried fixed encounter tuning, hit a problem with the optional side content where players arrive underleveled, and moved to fixed tuning with a one-time catch-up grant. That arc is the most valuable documentation your project will produce, and it only exists if you refuse to overwrite.
Statuses worth having:
- Proposed — written up, not yet agreed. Useful for async teams; the entry becomes the discussion thread.
- Accepted — live. This is the default reading state.
- Superseded by DL-### — replaced. Keep the text intact.
- Reversed — you went back to the earlier state. Worth distinguishing from superseded, because "we tried it and undid it" is a different signal than "we found something better."
Where it lives
The log has to be one click from wherever design work already happens, or it will not get written. If your design docs are in GameDesignerX, the Decision Log module sits alongside the idea, issue and risk logs and links directly to the chapters, mechanics and balance sheets an entry constrains — which matters, because the second-most-common failure mode (after not writing entries) is writing them somewhere nobody looks. A markdown folder in the repo works too, if your designers live in the repo. A Notion database works if that is genuinely your team's home. Slack does not work; nothing in Slack is findable in month nine.
Whichever tool you pick, get two things right: stable IDs (DL-032 must always mean DL-032, so use sequential numbers rather than titles as identifiers), and full-text search.
Making it a habit
Three practices, in order of how much they help:
- End of every design meeting, five minutes. Before people leave, ask "what did we decide?" and write the titles down. Fill in context and alternatives afterwards; the titles are the part that gets lost.
- Link entries from the artefacts they constrain. A note at the top of the balance sheet saying "encounter tuning per DL-032" costs nothing and answers the question at the point where it gets asked.
- Read the last ten entries at sprint start. Two minutes for the whole team. It catches superseded-but-not-marked entries and reminds people what is already closed.
The test of whether it is working is simple: when someone asks "why don't we have a jump?", the answer is a link, and the conversation is over in thirty seconds. That is the entire return on the four minutes.