Log Session

Capture the why and the what-next of a working session — the context that git history alone never records. A commit says what changed; a session log says what you were trying to do, what you decided, and where to resume.

Deliberately cheap (sonnet/medium): this is structured summarization, not judgment. It must never reach for an expensive model.

When to use

• Before `/clear` — you're about to wipe context; capture it first.
• Before closing Claude Code for the day.
• At a natural stopping point — a feature paused mid-way, a thread you want

to be able to resume cold.

• After a long session with several decisions worth remembering.

This is the manual, rich counterpart to the lightweight auto-logging hooks the template/ ships (see template/.claude/). The hooks capture the mechanical facts for free on every exit; this skill writes the thoughtful entry when you want one.

Step 0 — Discover the project (always first)

Per the agent guide's Workflow conventions + documentation map, locate the session log. Default path: docs/LOGS.md. If the documentation map names a different location, use that. If no log file exists yet, create it from the shape in template/docs/LOGS.md (a short header + the entry format below) and say so.

If a session-start marker exists (.claude/.session-*.start, written by the template's SessionStart hook), read it to bound the session precisely — it holds the HEAD sha and start time at session open.

Process

1. Establish the session boundary.

• If a marker is present, the session spans marker_sha..HEAD plus any

uncommitted work.

• Otherwise, use your own conversation context as the source of truth for

what happened this session, and corroborate with git log of the recent commits and git status / git diff --stat for uncommitted changes.

1. Gather the mechanical facts (cheaply, with git):

• branch (git branch --show-current),
• commits this session (git log --oneline <since>..HEAD),
• files touched (git diff --stat <since>..HEAD + uncommitted).

1. Write the narrative — the part only you can add:

• Summary: 1–3 sentences on what this session set out to do and what

actually got done.

• Decisions: the non-obvious choices made and why (the rationale that

would otherwise be lost). Link related docs/issues.

• Next: the concrete next step(s) — the command to run, the unfinished

thread, the open question. Write it so a cold reader knows exactly where to resume.

1. Append the entry to docs/LOGS.md, newest at the bottom (append-only,

chronological). Use this format so the auto-hook entries and these stay compatible:

   ## <ISO-8601 timestamp> — <branch> — manual
   - **Commits:** <n> (`<short-sha>…<short-sha>`)
   - **Files:** <comma-separated paths, or a count if many>
   - **Summary:** <what this session did>
   - **Decisions:** <key choices + why; omit the line if none>
   - **Next:** <the concrete next step>

If the user passed a note as an argument, prepend it to the Summary.

1. Commit policy. docs/LOGS.md is documentation — keep it coherent, but do

not open a PR just for a log entry. If you're mid-feature on a branch, the entry rides along with the next commit. If the working tree is otherwise clean and the user wants it persisted, ask before committing a standalone docs(log): session <date> commit. Never push without the project's push convention.

Guardrails

• Never use an expensive model for this. It's summarization; sonnet is the

ceiling, and the hooks do the free mechanical version.

• Don't invent facts. Decisions and next steps come from the actual session

(your context + git), not plausible-sounding filler. If a section has nothing real, omit its line rather than padding.

• Append, never rewrite. Past entries are a historical record — don't edit

or "tidy" them. Same reasoning as not rewriting a delivered feature's planning artifacts.

• One file, append-only. Don't fan session logs across files.

Relationship to other skills

• Complements the template/'s SessionEnd hook (free, mechanical, automatic

on /clear and exit) and the opt-in SessionStart restore hook (re-injects the last entry to resume context). This skill is the rich, manual entry.

• Pairs with execute-phase's per-feature progress.md: that tracks progress

within a feature; the session log is cross-cutting — whatever you touched this session, across features/fixes.

• Not part of the PR gate — it's a working-memory aid, not a merge artifact.

Done when

• A new entry is appended to docs/LOGS.md with at least Summary and Next.
• The mechanical facts (branch, commits, files) are accurate to git.
• The next step is printed — typically: /clear is now safe (the session is

captured), or the resume command named in the entry's Next line.