session-log（会话日志）

Session Log

Human-readable markdown logs that tell stories.

Session logs are living documents that capture the narrative of play. Unlike technical event logs, sessions are meant to be READ — by users, by future LLMs warming context, by anyone who wants to understand what happened.

[!IMPORTANT] Session logs are NOT append-only! They are living documents that grow and improve over time. You can and should retroactively improve them as new information comes in.

📍 Where Sessions Live

The default session file is SESSION.md in the character directory:

characters/
├── real-people/don-hopkins/
│   ├── CHARACTER.yml
│   └── SESSION.md          ← Default session log
├── fictional/donna-toadstool/
│   ├── CHARACTER.yml
│   └── SESSION.md          ← Default session log
└── animals/monkey-palm/
    ├── CHARACTER.yml
    └── SESSION.md          ← Default session log

Naming Sessions

You can create multiple session files with descriptive suffixes:

Command: START SESSION [name] — Creates a new session file with optional suffix.

📝 Writing Good Sessions

The Golden Rule

Sessions are meant to be read by humans. Write them like stories, not logs.

Structure with Outlines

Use <details open> tags to create collapsible sections that:

• Show narrative meant to be read (opened)
• Hide technical data and debugging (closed)
• Group related content into logical sections
• Allow readers to drill down on demand

<details open>
<summary><h2>🌟 Chapter Title — Descriptive Subtitle</h2></summary>

The narrative content goes here. This is what readers see first.

<details open>
<summary>📂 <strong>Technical details: What the YAML changes looked like</strong></summary>

The YAML data island

state_change: file: ./CHARACTER.yml changes: [location, inventory]

### Outline Patterns

| Pattern | When to Use | State |
| --- | --- | --- |
| `<details open>` | Narrative chapters — always show | **Open** |
| `<details open>` | Technical details — hide by default | **Closed** |
| Nested `<details open>` | Data within narrative | Mixed |

### The Summary Line

The `<summary>` is part of the narrative! Write it as a headline:

<!-- BAD: Generic summaries --> <summary>Turn 5</summary> <summary>File operations</summary>

<!-- GOOD: Descriptive headlines --> <summary><h2>🌟 Turn 5: The Wish is Spoken — Palm's Incarnation</h2></summary> <summary>📂 <strong>File creation: CHARACTER.yml with 32 Mind Mirror dimensions</strong></summary>

### Use Emojis in Section Headers

Add emojis **after the folder icon** for narrative sections:

| Emoji | Meaning |
| --- | --- |
| 📂 | Technical/collapsed section |
| 🌟 | Major milestone |
| 🎭 | Character transformation |
| 🗺️ | Exploration/travel |
| 💬 | Dialogue/conversation |
| 🎰 | Games/randomness |
| 🐕 🐱 🐵 | Animal character sections |
| ⚡ | Speed-of-light simulation |

---

## 📊 Session Index

**Keep an index at the top of every session!** Update it retroactively as you append.

<details open> <summary><h2>⭐ Session Highlights & Index</h2></summary>

📚 Session Index (Internal Links)

Day 1 — The Wish

• 🌿 LOOK AROUND — First impressions
• Turn 1: Talk to Marieke — Lucky strains
• Turn 7: THE WISH IS SPOKEN — 🌟 Palm's incarnation

Day 2 — The Fluxx Marathon

• 🎰 33 Turns of Gezelligheid — Speed of Light demo

🏠 Key Locations (External Links)

</details>

### Index Rules

1. **Internal links** use anchor syntax: `[Title](#anchor-name)`
2. **External links** use relative paths: `[File](../../../path/file.yml)`
3. **Update retroactively** — every append is a chance to improve the index
4. **Group by day/arc** — natural narrative divisions

---

## 🔗 Linking Generously

**Links draw people into the repo!** Every file, character, room, and skill mentioned should be a link.

### Link Everything

<!-- BAD: No links --> Palm wrote an essay about being a monkey.

<!-- GOOD: Link everything --> Palm wrote an essay (palm-on-being-palm.md) about being a monkey.

### Use Tables for Related Files

Files Created

Related Skills

> **Path variables in YAML vs Markdown:** Use `$SKILLS/` in YAML files (runtime resolution). Use relative paths in Markdown for GitHub rendering.

---

## 📈 Tables Tell Stories

Tables are excellent for:

- **Summarizing actions** — turns, outcomes, stats
- **Showing state** — inventories, relationships, locations
- **Listing files** — what was created, edited, linked
- **Character rosters** — who's present, their status

Current Status

Session Statistics

### Fold Large Tables

<details open> <summary>📂 <strong>Full inventory (47 items)</strong></summary>

</details>

---

## 🔄 Retroactive Improvement

**Sessions are living documents.** Every time you append:

1. **Update the index** — add new sections, fix anchors
2. **Add missing links** — file paths, character names
3. **Improve summaries** — make them more descriptive
4. **Fill in context** — as you learn more, annotate earlier sections
5. **Fix broken links** — paths change as files move

### Ninja Edits

Small retroactive improvements are encouraged:

- Correcting typos
- Adding links to newly-created files
- Improving section summaries
- Updating the index

---

## 📋 YAML Data Islands

Embed structured data in fenced code blocks for machine readability:

<details open> <summary>📂 <strong>State change: Moving player from start/ to coatroom/</strong></summary>

state_change:
  file: ./CHARACTER.yml
  changes:
    player.location: "coatroom/"  # Was: "start/"

  file: ../../../ADVENTURE.yml
  changes:
    player.location: "coatroom/"  # Mirror update

Data Island Best Practices

🆚 Session Logs vs Event Logs

Create event logs for:

• Technical debugging
• Append-only audit trails
• Machine-parseable history

Create session logs for:

• User-facing narrative
• GitHub browsing
• Context warming
• Storytelling

🌟 Examples: Gold Standard Sessions

These sessions demonstrate best practices:

Don Hopkins' Marathon Session

examples/adventure-4/characters/real-people/don-hopkins/sessions/marathon-session.md

7000+ lines spanning 5 days of adventure. Demonstrates:

• Extensive use of collapsible sections
• Comprehensive index at top
• Generous linking to files and skills
• Tables for menus, stats, and rosters
• Speed-of-light simulation transcripts
• Technical details hidden in collapsed sections

Donna Toadstool's Session

examples/adventure-4/characters/fictional/donna-toadstool/SESSION.md

Complete character creation narrative. Demonstrates:

• Table of contents with parts
• Character transformation documentation
• File operation explanations
• Appendix with technical reference
• Clear separation of narrative and data

🎯 Quick Reference

Starting a New Section

---

<details open>
<summary><h2>🌟 Turn N: Title — Descriptive Subtitle</h2></summary>

Narrative description of what happened.

<details open>
<summary>📂 <strong>Technical: What changed under the hood</strong></summary>

changes: - file: path/to/file.yml field: value

### Checklist for Every Append

- Updated index at top with new section
- Added links to all mentioned files
- Linked character names to their directories
- Used collapsible sections appropriately
- Wrote descriptive summary lines
- Included relevant tables
- Fixed any broken links noticed

---

## The Intertwingularity

Session-log is the PLAY stage of [play-learn-lift](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../play-learn-lift/) — capture everything.

graph LR SL[📜 session-log] -->|PLAY stage of| PLL[🎮 play-learn-lift] SL -->|tracks| R[🚪 room] SL -->|tracks| TC[🎴 card] SL -->|monitored by| SR[🔧 self-repair]

AP[⚔️ adventure] -->|LOG.md is| SL DB[🔧 debugging] -->|logs to| SL CH[👤 character] -->|SESSION.md is| SL

---

## Dovetails With

### Sister Skills

| Skill | Relationship |
| --- | --- |
| [character/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../character/) | Session files live in character directories |
| [adventure/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../adventure/) | Adventure LOG.md follows session-log patterns |
| [play-learn-lift/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../play-learn-lift/) | Session-log is the PLAY capture stage |
| [summarize/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../summarize/) | Compress session-log when too long |
| [self-repair/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../self-repair/) | Monitors session-log integrity |
| [debugging/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../debugging/) | Debug sessions log here |

### Protocol Symbols

| Symbol | Link |
| --- | --- |
| `SESSION-LOG` | [PROTOCOLS.yml](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../../PROTOCOLS.yml#SESSION-LOG) |
| `NARRATIVE-FIRST` | Write for humans |
| `LINK-GENEROUSLY` | Every file is a link |

### Kernel

- [kernel/event-logging-protocol.md](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../../kernel/event-logging-protocol.md) — Technical event format
- [schemas/event-schema.yml](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../../schemas/event-schema.yml) — YAML block schema

### Navigation

| Direction | Destination |
| --- | --- |
| ⬆️ Up | [skills/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../) |
| ⬆️⬆️ Root | [Project Root](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../../) |
| 🎮 Sister | [play-learn-lift/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../play-learn-lift/) |
| 👤 Sister | [character/](https://github.com/simhacker/moollm/blob/HEAD/skills/session-log/../character/) |