/session-log

name: session-log
description: >
  USE WHEN ending a substantial working session — user says
  "thanks/tomorrow/wrap up", or session shipped 3+ commits with no log
  today, or user asks for a summary. Distills the conversation into
  `docs/sessions/YYYY-MM-DD-<topic>.md` (context, what was done, key
  decisions, open questions, next steps). Hard cap ~80 lines.
  Distillate, NOT transcript. See `docs/sessions/README.md`.
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Bash(git rev-parse:*)
  - Bash(git log:*)
  - Bash(git branch:*)
  - Bash(date:*)
  - Bash(ls:*)
argument-hint: "[topic-one-liner] [--noninteractive]"

/session-log

What it does

At the end of a working session, writes a short distilled summary to `docs/sessions/YYYY-MM-DD-<topic>.md` following the standard template (context, what was done, key decisions, open questions, next steps, references). The next agent — yours tomorrow, or a different agent in a month — reads it to pick up the thread without re-discovering everything cold.

This is **not a transcript dump**. Raw chat is noise the next agent can't usefully consume. A session log is the *distillate*: 30–80 lines that compress a multi-hour conversation into actionable continuity.

Workflow

1. **Find target dir.** Default `docs/sessions/` from the current repo root (via `git rev-parse --show-toplevel`). If it doesn't exist, ask "create it now?" — if yes, create with a stub `README.md` describing the convention (mirror the one shipped with this plugin at [`docs/sessions/README.md`](../../docs/sessions/README.md)).

2. **Get topic.** If `$ARGUMENTS` has a positional, use it. Otherwise ask: "what was this session about, in one line?" Convert to kebab-case for the filename: `2026-05-24-pivot-cleanup.md`.

3. **Compute filename.** `YYYY-MM-DD-<kebab-topic>.md`. If a file with the same name exists (multiple sessions on the same topic same day), suffix with `-2`, `-3`, etc.

4. **Gather facts** from git and the conversation:

• Current branch: `git rev-parse --abbrev-ref HEAD`.
• Recent commits this session: `git log --oneline -10`. Use the

first commit hash *after* the previous session's HEAD if you can infer it, otherwise show the last 5–10 with the human confirming which ones belong.

• Conversation summary: distill from the actual chat above (you,

the model, have access). Categorize into:

• **What was done** — concrete actions: code shipped, decisions

recorded, files moved, skills added. Bullet list.

• **Key decisions** — non-obvious calls made in conversation.

Link to ADRs if applicable (suggest `/adr-new` for any decision likely to be re-litigated).

• **Open questions** — anything deferred or unresolved.
• **Next steps** — what should happen first in the next session.

5. **Generate the file** using the template ([`docs/sessions/template.md`](../../docs/sessions/template.md)). Substitute:

• Topic, date, branch, participants (you + model name).
• Each section filled from step 4. Use `<TODO>` for anything you

genuinely can't infer; better an honest gap than a fabrication.

6. **Confidentiality pass.** This file gets committed and pushed — sometimes to a public repo. Before writing, scrub anything that shouldn't ship: secrets, credentials, client names, internal business reasoning, security details. Keep the *decision*, drop the sensitive specific ("chose vendor X for pricing reasons" → "chose the payments vendor; rationale in the private tracker"). See the Hard rule below.

7. **Hard cap on length.** If your draft is over 80 lines, reduce. Cut the "what was done" bullets to the load-bearing 5–8. Move tactical detail into commit messages, ADRs, or specs. The session log is *pointers + decisions + next-actions*, not a play-by-play.

8. **Report.** Print the file path and one line: > "Next session: start by reading `docs/sessions/<filename>` plus > the last 1–2 prior session logs."

Hard rules

• **Logs are committed — write for a public reader.** `docs/sessions/` is

a tracked, durable artifact that gets pushed, sometimes to a public repo. Never put secrets, credentials, client names, internal business reasoning, or security details in a log. The `block-secrets-precommit` hook catches key-shaped secrets at commit time, but it **cannot** catch confidential *prose* — that judgment is yours. Distill the sensitive specifics out: write "the client" not the name; reference a private ticket by ID rather than pasting its content. Gitignore `docs/sessions/` only as a last resort in a fully public repo where even the distilled narrative shouldn't ship (you lose cross-agent continuity if you do).

• **Distillate, not transcript.** If the user asks "include the full

conversation," push back. The full conversation is in Claude Code's session history; the journal is for future-agent consumption.

• **No fabrication.** If you don't know what "was done" because the

conversation was mostly planning, write that explicitly: *"Session was planning-only — no code shipped. Plan landed in `docs/specs/<file>`."*

• **Link, don't duplicate.** ADRs, specs, commits get linked by

number/hash — never copied into the session log body.

• **Pre-existing session logs are immutable.** If you're amending,

write a new dated file (`-2`, `-3` suffix) rather than editing.

Tunables

• `--noninteractive` — skip prompts; requires a topic positional.

Pulls everything else from git + the visible conversation context.

• `--dry-run` — print the generated content to stdout, write nothing.

When to invoke

• **End of a substantial working session.** Substantial = anything

that shipped a commit chain or made a load-bearing decision.

• **NOT after a quick one-shot fix.** A 5-minute typo fix doesn't

need a journal entry; the commit message is enough.

• **NOT after a pure-exploration session.** If you didn't decide

an