Session log

Use this when

You are ending a session and want to write a proper record, or you are picking up a session where someone else left off and want to know what happened last time.

Skip this when

You are mid-session. Session logs are session-end artifacts. Mid- session state lives in docs/whereami.md.

What it is

A session log is a Markdown file with YAML frontmatter that names what one session accomplished. Every session that ships substantive work writes one at close.

Path: chronicle/YYYY-MM-DD-<slug>.md (bassclef repo) or docs/chronicles/YYYY-MM-DD-<slug>.md (adopter repo).

Storage shape: Shape B (Markdown + YAML frontmatter) per state-spine.

Sections a session log carries

• Frontmatter — session id, date, active goal reference, phase, outcome
• What shipped — commits, PRs opened, artifacts produced
• What was decided — new ADRs, canvas amendments, scope shifts
• What's still open — items paused, deferred, or handed off to the next session
• Gate evidence — which gates fired (temperance, verify, diagnose) with markers

The chronicle-template.md at templates/ in bassclef ships the full shape.

↗templates/chronicle-template.md

Who writes it

The /session-end skill writes the session log as one of its MUST- tier obligations. The /session-log skill (formerly /chronicle, renamed 2026-06-25 per ADR-040) drafts the body from the session's commits + conversation.

Session-end is run at the end of every substantive session. It composes /session-log to produce the record.

Session-end vs. session-rescue

Sometimes the session ends before /session-end fires — context exhaustion, sandbox teardown, OS interruption. When that happens, the Stop hook writes a session-rescue deferred-action entry. The next session sees the entry as BLOCKED: and completes the missing obligations.

Session-rescue is the safety net. Session-end is the primary path.

Related concepts

• State spine — Shape B storage shape
• Whereami primitive — the singleton project-state snapshot that session-end updates