session-log

/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)).

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

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

1. Gather facts from git and the conversation:
2. Current branch: git rev-parse --abbrev-ref HEAD.
3. 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.

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

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

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

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

anything and didn't ship anything, there's no continuity to preserve.

A useful rule of thumb: would the next agent benefit from knowing where this session left off? If yes, write the log. If no, skip.

Pairs with

• /adr-new — when a session produces a load-bearing decision,

record it as an ADR in addition to the session log. The session log is "what happened this session"; the ADR is "the durable reason for the choice."

• AIDEV-TODO anchors with deadlines — for "next steps" items that

bind to specific code paths, anchor them in code with AIDEV-TODO(by: YYYY-MM-DD): and reference from the session log.

What this skill does NOT do

• Doesn't read the future. The "next steps" section is what you

think should happen, distilled from the conversation. The model doesn't predict.

• Doesn't replace commit messages, ADRs, or specs. Each layer

serves a different purpose:

• Commit message: per-commit what.
• ADR: per-decision why (immutable).
• Spec: per-feature plan (lives through implementation).
• Session log: per-working-period narrative (continuity).