From acf1b2cf95d4ca0ca374ef9e0b128384df98b1e4 Mon Sep 17 00:00:00 2001 From: hypercross Date: Sun, 13 Sep 2026 16:50:22 +0800 Subject: [PATCH] docs(skills): add consistency and perception steps run-session now checks the outcome against established facts and narrates only what the PC can perceive, with retconning as a last resort. --- .agents/skills/run-session/SKILL.md | 80 ++++++++++++++++++++++++----- 1 file changed, 67 insertions(+), 13 deletions(-) diff --git a/.agents/skills/run-session/SKILL.md b/.agents/skills/run-session/SKILL.md index 755e495..f054f6d 100644 --- a/.agents/skills/run-session/SKILL.md +++ b/.agents/skills/run-session/SKILL.md @@ -1,14 +1,14 @@ --- name: run-session -description: Run a turn or a full session of a solo journaling campaign. Use when the player describes what their character does, asks to start or continue a session, or asks what happens next. Interprets the message as in-fiction intent, rolls through the journal CLI, narrates the outcome in chat, appends it to the session log, and updates the PC sheet, clocks, threads, and world files. +description: Run a turn or a full session of a solo journaling campaign. Use when the player describes what their character does, asks to start or continue a session, or asks what happens next. Interprets the message as in-fiction intent, rolls through the journal CLI, checks the outcome against established facts, narrates only what the PC can perceive, appends it to the session log, and updates the PC sheet, clocks, threads, knowledge, and world files. --- # Running a session The player types their intent into chat, exactly as they would request a code -change. Everything else is your job: resolve it with dice, narrate, and persist -the result to the campaign's files. `AGENTS.md` holds the contract; this skill -is the procedure for a single turn. +change. Everything else is your job: resolve it with dice, narrate what the PC +perceives, and persist the result. `AGENTS.md` holds the contract; this skill is +the procedure for a single turn. The player never edits files. If you narrated it, write it down. @@ -23,8 +23,10 @@ Do this once, before the first turn. 2. **Read the campaign's game** from `campaigns//campaign.md` frontmatter (`game: `). Read `games//game.md` — it is authoritative — plus `campaigns//house-rules.md`. -3. **Load state.** Read the PC sheet(s) in `characters/`, `state/clocks.md`, - `state/threads.md`, and the tail of the newest `sessions/NNNN-*.md`. +3. **Load state.** Read the PC sheet(s) in `characters/`, + `state/knowledge.md`, `state/clocks.md`, `state/threads.md`, the relevant + `world/` files and `gm/` notes, and the tail of the newest + `sessions/NNNN-*.md`. 4. **No PC yet?** Build one from the game's `characters/` options (roll them with `journal ` where the game provides one), write the sheet to `campaigns//characters/.md`, and say what you created. @@ -76,11 +78,50 @@ journal --campaign ashfall Never invent, reroll, or adjust a result. If a roll is not interesting, the mistake was calling for one — narrate from the fiction instead. -## 5. Narrate and append +## 5. Check consistency -Resolve the intent into a concrete outcome, then append one scene to the -current session log using the format in `AGENTS.md`. Copy -`templates/session.md` for a new file. +Before you narrate, hold the outcome up against what is already established. + +- Re-read the relevant `world/` files, `gm/` notes, prior scenes, clocks, + threads, and the PC sheet. +- Does it contradict a fact, a disposition, a location's state, who knows what, + an injury, a promise, or a rule? The established fact wins. +- A contradiction is often the point: if the result means an earlier belief was + wrong, play it as a revelation. Never quietly rewrite a past scene. +- If the scene needs a detail that is not established, get it from a spark table + or the oracle, or leave it unstated. Do not improvise a fact that will + constrain you later. + +**Retconning** is the last resort. If — and only if — a contradiction has no way +forward, you may change the fact instead. The constraint is perception: after +the change, every session-log entry and everything in `state/knowledge.md` must +still read exactly as before. You may rewrite the hidden cause; you may never +rewrite what the PC saw, heard, or was told. Use it to repair a dead end, not to +escape a consequence the fiction earned. Record every retcon in +`gm/retcons.md`. + +## 6. Narrate what the PC perceives + +The log and the chat reply are the PC's experience, not your notes. Filter the +outcome through: + +- **Senses and position** — what can they see, hear, smell, or touch from where + they are? +- **What they know** — `state/knowledge.md`. Do not reference a fact they have + not learned. +- **Their frame** — describe an unfamiliar thing as it appears, in the words the + PC would use, not your term for it. +- **Effects, not causes** — if something hidden acts, show what it does, not + why. + +Withhold hidden causes, identities, and off-screen events; those live in `gm/` +and surface only when observed. If a roll produced something the PC cannot +perceive, narrate what they do notice, or nothing at all. + +## 7. Append and reply + +Append one scene to the current session log using the format in `AGENTS.md`. +Copy `templates/session.md` for a new file. - If you rolled, put the CLI output in backticks, verbatim. - Omit the roll line when no roll was needed. @@ -88,7 +129,7 @@ current session log using the format in `AGENTS.md`. Copy - **Reply in chat with the same resolution prose**, so the player can read it without opening the file. Keep chat and file consistent. -## 6. Apply state changes +## 8. Apply state changes The scene is not finished until the files match the `State` line. @@ -97,7 +138,10 @@ The scene is not finished until the files match the `State` line. | Stat, track, condition, inventory | `campaigns//characters/.md` frontmatter | | A clock filled or advanced | `campaigns//state/clocks.md` | | A thread opened, resolved, abandoned | `campaigns//state/threads.md` | -| A place, person, or faction first appears | new file under `world/` | +| Something the PC learned, confirmed, or came to believe | `campaigns//state/knowledge.md` | +| A new truth the PC has not perceived | `campaigns//gm/` | +| A fact you changed after the fact | `campaigns//gm/retcons.md` | +| A place, person, or faction first appears | a new file under `world/` | | Something changes about an existing one | that file | | A rule shape that emerged in play | `campaigns//house-rules.md` | @@ -110,6 +154,10 @@ defines. points out. - **Do not decide what the PC wants.** The oracle answers the world; the player answers the character. +- **Never narrate what the PC cannot know.** A `gm/` fact stays hidden until it + is observed or told. +- **Established facts beat convenience.** If a scene wants to contradict one, + make the contradiction a revelation rather than an erasure. - **Never copy game content into a campaign.** Reference the game package. - **Keep frontmatter and prose consistent.** If the log says a stat changed, the sheet must show it. @@ -120,7 +168,9 @@ When the player stops for the night: 1. Run `journal check --campaign ` and fix anything it reports. 2. Make sure every `State` line has been applied. -3. Leave `state/threads.md` reflecting what is unresolved. +3. Make sure `state/knowledge.md` reflects what the PC learned, and `state/threads.md` + what is unresolved. +4. Move anything newly true but not yet perceived into `gm/`. ## Common failures @@ -130,4 +180,8 @@ When the player stops for the night: - Writing a `State` line but not applying it to the files. - Editing an earlier scene to "fix" continuity instead of writing the fix forward. +- Leaking a `gm/` secret into the log or the chat reply. +- Narrating a cause when the PC only perceives the effect. +- Contradicting an established fact to make the current scene work. +- Reaching for a retcon when writing forward would do. - Acting on the wrong campaign when several exist — ask first.