solo-journaling/.agents/skills/run-session/SKILL.md

---
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, 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 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.

## 1. Bootstrap the session

Do this once, before the first turn.

1. **Identify the campaign.** `journal games` lists games; the campaign is
   `campaigns/<name>/`. If the player named one, use it. If several exist and
   they did not, ask — do not guess. Only `campaigns/` directories without a
   leading `_` count.
2. **Read the campaign's game** from `campaigns/<name>/campaign.md` frontmatter
   (`game: <id>`). Read `games/<id>/game.md` — it is authoritative — plus
   `campaigns/<name>/house-rules.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 <command>` where the game provides one), write the sheet to
   `campaigns/<name>/characters/<pc>.md`, and say what you created.
5. **Pick the session file.** Continue the newest one, or start the next:
   `NNNN` is the previous number plus one, zero-padded to four digits, with a
   kebab-case slug from the opening situation. Use `templates/session.md`.

## 2. Read the player's message

- **In-fiction intent** — the player describing what the PC does, tries, or
  asks. This is the main case: go to step 3. Record their words *verbatim* in
  the `Player` block.
- **Meta request** — a rules question, a recap, "what are my stats?", "start a
  session". Answer from the files. Do not roll, do not append a scene, and do
  not treat it as intent.

When a message is ambiguous, answer the meta part and ask whether they want the
action attempted.

## 3. Decide whether to roll

Roll only when the outcome is genuinely uncertain *and* both results would be
interesting. Do not roll for trivial actions, for what the fiction already
settles, or to decide what the PC wants.

- **Oracle** — a yes/no question about the world: "Is the gate locked?" Ask one
  question at a time, phrased so either answer is interesting.
- **Spark table** — generating content: a location detail, an NPC's trait, what
  happens next.
- **Complication** — on `and`/`but` results, or when the fiction needs a twist.
- **The game's own resolution** — if `game.md` defines one, follow it and use
  `journal dice` for its rolls, or the game command it provides.

If the game ships a command for what you are about to do, use the command
rather than reimplementing it by hand.

## 4. Roll

Always pass `--campaign <name>`. Use the CLI's output exactly as printed — it
already renders the oracle's label, so relay that rather than re-deriving it.

```sh
journal oracle "Is the gate locked?" --complicate --campaign ashfall
journal roll sparks --campaign ashfall
journal dice 2d6+1
journal <game-command> --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. Check consistency

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.
- List every mechanical change on the `State` line.
- **Reply in chat with the same resolution prose**, so the player can read it
  without opening the file. Keep chat and file consistent.

## 8. Apply state changes

The scene is not finished until the files match the `State` line.

| Change | File |
|--------|------|
| Stat, track, condition, inventory | `campaigns/<name>/characters/<pc>.md` frontmatter |
| A clock filled or advanced | `campaigns/<name>/state/clocks.md` |
| A thread opened, resolved, abandoned | `campaigns/<name>/state/threads.md` |
| Something the PC learned, confirmed, or came to believe | `campaigns/<name>/state/knowledge.md` |
| A new truth the PC has not perceived | `campaigns/<name>/gm/` |
| A fact you changed after the fact | `campaigns/<name>/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/<name>/house-rules.md` |

Never invent stats the game does not use. Keep the frontmatter shape the game
defines.

## Continuity rules

- **Append only.** Never edit a past scene except to fix a typo the player
  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.

## Closing a session

When the player stops for the night:

1. Run `journal check --campaign <name>` and fix anything it reports.
2. Make sure every `State` line has been applied.
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

- Inventing a dice result, or rolling without calling the CLI.
- Rolling when the fiction already answers the question.
- Paraphrasing the player in the `Player` block instead of quoting them.
- 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.