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

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

#