Debugging a GM turn
When the GM does something you didn't expect, you don't have to guess why. Every GM turn keeps a record of exactly what the GM was sent and everything it did, and you can read it whole. Most surprises turn out to have a plain cause: an instruction that said to do it, a fact the GM never had, or two rules that disagree.
What a turn's record holds
A turn's record is saved when the turn ends. It holds:
- The system prompt: everything the GM is told on every turn, from Craft's own instructions to the world's GM instructions, the options picked for this game and the trackers. Its headings are listed with where each one starts, so you can read one part on its own.
- The messages the turn opened with: the scene, earlier play and the GM's memory of it, the rules for this moment, and the player's move.
- Everything the GM did that turn, step by step: its thinking, each tool it called and what came back, and its reply.
- The turn's facts: the game and the world it was started from, the GM's model, how many calls it made, how long it took and how many tokens it used.
- How the turn ended: whether it told a reply, how each model call finished, and any error that stopped it, such as a dropped connection to the model's provider, with what that error means.
The record holds the GM's hidden notes and the world's secrets, so reading it can give the plot away.
The request id
Every message in a game has a request id: a long id like
866ed0cc-36fe-48f8-85a3-58928ede9739, copied with Copy request ID in
the message's ⋯ menu (the message menu). It
names the turn's record. A bare id like that, pasted with little or no
explanation, is most likely a GM turn's request id.
Only turns of games you play can be read.
Reading it
To read a turn, open Inspect turn from the reply's ⋯ menu. Then work from the top:
- Start from the overview: the prompt's headings and every message on one line. In Inspect turn that is the panel's three sections: System prompt, Initial Message Array and This turn.
- Search for the words of what went wrong: a name, a rule, a number. A search shows where they appear in the prompt, under which heading, and in which message. Type them in the search box at the top; the arrows, or Enter, step from match to match.
- Read the part that matters in full. Open the System prompt section to read the prompt, and click a message's line to read it whole.
A tool result that reads [pruned] was shown to the GM in full during
its own turn and cut afterwards, to save tokens on later turns. The GM
saw it when it mattered.
In a game, Debug with Orbit in a GM reply's ⋯ menu asks what was wrong with the turn and opens a new Orbit chat about it: Orbit reads the same record and quotes the instruction or step behind what happened. You can also paste a request id into Orbit, or into a coding agent working on your world with the Craft CLI, with your question.
Finding the cause
Look for the exact instruction, tool result or step behind what happened, and note where it is: a prompt heading, or the message's number. The usual causes, and where each is fixed:
- One of the world's instructions. A GM instruction or a game option said to do it, or two of them disagree. Fix it in the world's GM instructions: reword the one rule, or merge the two that argue.
- Missing context. What the GM needed wasn't in the prompt or in any tool result it got: a file it didn't read, or a fact that is nowhere in the world. Add the fact to the world, or make it easier to find with a clear name, the key facts up front and links between files (working with AI).
- A rule that didn't fire. A situational instruction for the moment wasn't given to the GM, because its trigger didn't match the player's move or the end of the last reply. Reword the trigger (triggers).
- The model. The instruction and the context were there and the GM still got it wrong. Some models can't do some things reliably, however they are told, above all in how they write. Switch the game to a stronger model and Rewrite the turn: if that gets it right, the instructions are fine.
- A script or computed field. A number came out of code with a mistake in it. Fix the script or the computed field.
- Craft itself. Something in the part of the prompt the world doesn't control caused it. Report it in the bug reports channel of Craft's Discord, with the request id.
To repair the game itself (a wrong number on a sheet, a reply to undo), see fixing a game.
Doing it well
- Look before you guess. The record shows what the GM was told, so a theory about its reasons can be checked in a minute.
- Search for the exact words. The name or number that went wrong finds the instruction or result behind it faster than reading in order.
- Fix the cause once, in one place. A second rule that argues with the first adds to the noise the GM has to weigh.