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

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