Game design decision log: record what was decided and why
For game designers, leads and producers who keep hearing "why did we do it this way?". You get what a useful decision record contains, when to write one, and how to keep a decision log in Gameheim that stays connected to bugs and to the changelists that implemented it.
Why game teams forget why a design decision was made
A game changes shape many times before release. The dodge loses its invincibility frames, the inventory drops from 40 slots to 24, the tutorial moves to the second level. Each change was discussed and agreed, usually in a meeting, a chat thread or a playtest review. Six months later nobody remembers the reason, and the same discussion starts again.
The cost is real, and it grows with the team:
- Decisions get undone by accident. A programmer fixes a "bug" that was the intended behavior, or a new designer restores an option that was removed for a good reason.
- Discussions repeat. Without the rejected alternatives written down, every newcomer proposes them again, and the team spends another meeting rejecting them.
- Decided is not the same as done. A decision agreed in March may never reach the build. Nobody notices until a playtest shows the old behavior.
- The design document drifts. The game design document says one thing, the build does another, and nobody can say which one is the current intent.
What a decision record for game teams contains
Software teams call this an architecture decision record. For a game team the same idea works for design, art direction, technology and production choices. A good record is short and answers five questions:
- What was decided, in one line. "Dodge has no invincibility frames" is a decision. "Dodge rework" is a topic.
- Why. The problem it solves, the playtest data, the constraint (performance, budget, platform rules).
- What was rejected, and why. This is the part that stops the discussion from repeating.
- When, and on what basis. The date and the source: the design document section, the meeting notes, the playtest report.
- Where it stands. Proposed, decided, replaced by a newer decision, or cancelled, and whether it is in the build yet.
Write a record when a choice is expensive to reverse, when it surprised someone, or when it was discussed more than once. Small tuning values do not need one; a change of mechanic does.
How Gameheim keeps a design decision log connected to the game
Gameheim has a Decisions register in every project, next to tasks and bugs. Each decision has a key such as OFT-DEC-3 and holds the five parts above: the decision, the Rationale, the Rejected alternatives, the Date and Source, and a Status. What makes it more than a document is what it is connected to:
- Is it in the code? The In code field is your team's judgment (Yes, Partly, No, Not applicable). Next to it, Gameheim lists the changelists that cite the decision. When the two disagree, the panel says so: "Declared «No», but changelists cite this decision", or the opposite.
- Decided, not in code. A dedicated view lists decisions marked Decided whose In code is not Yes: things the team agreed on and has not built yet.
- Superseded, with a link. When a decision is replaced, the old one points to the new one (Superseded by) and the new one shows Replaces. You can follow the chain of revisions instead of guessing which record is current.
- Linked to bugs. A decision lists the bugs it explains, and each bug shows its Linked decisions. A tester who files "the dodge has no invincibility" can be pointed to the decision instead of starting a debate. See bug tracking for game development.
- Linked to the design document. The source can be a page of the project wiki, so the decision points to the section it came from. See game design document wiki.
- Filed by system. Decisions use the same Systems as bugs (combat, UI, save system...), so you can list everything decided about one part of the game.
Decisions are also available to AI assistants connected to Gameheim, so a designer can ask "what did we decide about the inventory, and why?" and get the recorded answer. See AI assistants for game projects.
How to record and maintain a design decision in Gameheim
- You are a member of the project. The default Team Member (Default) role can read and record decisions (Decisions:
readandwritein Roles & Permissions). - Deleting a decision needs Decisions:
manage. LEAD accounts have it. - Systems are managed in the bug settings (Bugs, Settings), which needs Bugs:
manage. - Changelists link to decisions automatically only for submits made from the P4 Workspace in Gameheim.
Open the register and start a new decision
Click Decisions in the sidebar and select your project. Click New decision.
Write the decision and its reasons
In Decision, write what was decided in one line: it is the only required field. Fill Rationale with the reasons and Rejected alternatives with the options you discarded and why. Both are rich text, so lists and inline code work.
Set Status. A new decision starts as Proposed; choose Decided if it is already agreed. When a decision becomes Decided and has no Date, Gameheim fills in today.
Record the source and the systems
Under Source, pick a Wiki page of the same project, or type an Other source or section, for example
battle-spec.html §02or the date of a playtest review. Select the Systems the decision belongs to, then click Record decision.Note:Only pages you can read are offered as source. A teammate who cannot open that wiki page sees Wiki page (you cannot open it) instead of the link. If the page is deleted later, its title stays as the source text.Link the bugs it explains
Open the decision and, under Linked bugs, choose a bug and click Link bug. The link appears on both sides: the bug panel lists the decision under Linked decisions.
Cite the decision when you implement it
When you submit the work from the P4 Workspace, mention the decision key in the changelist description. The changelist appears under Changelists in the decision, marked named in submit. Unlike tasks and bugs, a decision has no
Changelist descriptiondonekeyword: the key only links the changelist. You can also add a changelist number by hand with Add changelist.Remove invincibility frames from dodge #OFT-DEC-3Then update In code to Partly or Yes. Gameheim does not change it for you: whether a decision is fully implemented is a judgment, and the changelists are the evidence next to it.
Supersede a decision instead of rewriting it
When the team changes its mind, do not edit the old record. Set its status to Superseded. Gameheim asks Which decision replaces this one?: pick an existing decision, or choose Write a new one to open a new decision already filled with the title, systems and source. When you save it, the old decision is marked as superseded by the new one.
The old decision stays readable with its link forward, so the history of the choice is kept. Gameheim refuses a loop (A replaced by B replaced by A).
Review the log regularly
Use the views at the top of the page: Needs review for decisions someone flagged, and Decided, not in code before a milestone, to catch agreed changes that never reached the build. Filters cover Status, System, In code and whether decisions have linked bugs.
Decision statuses
| Status | Meaning |
|---|---|
| Proposed | Written down for discussion, not agreed yet. The default for a new decision. |
| Decided | Agreed by the team. The date is filled in if it was empty. |
| Needs review | Still in force, but something changed (a playtest, a new constraint) and it should be discussed again. |
| Superseded | Replaced by another decision, which it links to. Cannot be chosen when creating a decision. |
| Cancelled | Dropped without a replacement. |
You can move a decision between statuses freely. Leaving Superseded removes the link to the replacing decision.
The In code field
| Value | Use it when |
|---|---|
| Yes | The decision is fully in the build. Gameheim warns if no changelist cites it. |
| Partly | Some of the work is in, some is not. |
| No | Nothing is implemented yet. The default. Gameheim warns if changelists already cite it. |
| Not applicable | The decision does not involve code or content, for example a process or scope choice. |
Decisions, tasks and notifications
- Decisions are not linked to tasks. To plan work that comes from a decision, create a task and cite the decision key (
OFT-DEC-3) in its description. See game development task tracking. - Decisions do not send notifications. To tell the team about an important one, post it in the project announcements or a topic (see team chat and announcements).
Troubleshooting
| What you see | Why, and what to do |
|---|---|
| A changelist did not appear on the decision | Only submits made from Gameheim are read, and the submitter must be able to write decisions. Check the key: #OFT-DEC-3, with DEC. On Git projects, commits are not linked automatically. |
| "The changelists do not match what is declared" | The In code value disagrees with the changelists. Update the field, or add the missing changelist. |
| Superseded is missing in the new decision form | A new decision cannot start as superseded. Create it, then supersede the old one from its panel. |
| The Delete decision button is missing | Deleting needs Decisions: manage. Superseding is usually the better choice, because it keeps the history. |
| You cannot pick a wiki page as source | Only pages of the same project that you can read are offered. |
Frequently asked questions
What is a design decision log in game development?
It is a list of the important choices made about a game, each with what was decided, why, which alternatives were rejected, when, and whether it has been implemented. It lets a team answer "why is it like this?" months later without repeating the discussion, and stops people from undoing a decision by accident while fixing bugs or reworking a system.
How is a decision log different from a game design document?
A game design document describes how the game should work today. A decision log records how you got there: each change of direction, its reasons and the options you turned down. The two work together. In Gameheim a decision can point to the wiki page it came from, so the document shows the current design and the decision explains it.
Which decisions are worth recording?
Record choices that are expensive to reverse, that surprised someone, or that were discussed more than once: a change of core mechanic, a cut feature, a target platform or engine choice, a scope reduction. Small tuning values that change every week do not need a record. If a new team member would reasonably ask why, write it down.
How do I know if a design decision was actually implemented?
In Gameheim each decision has an In code field set by the team, and a list of the changelists that cite its key, such as #OFT-DEC-3 in a submit description. When they disagree, the panel shows a warning. The Decided, not in code view lists everything agreed but not marked as fully implemented.
What happens when the team changes a decision?
Mark the old decision as Superseded and choose the decision that replaces it, or write the new one directly from the old panel. The old record stays readable with a link to the new one, and the new one shows which decision it replaces, so anyone can follow how the choice evolved.