--- name: session-notes description: > Write structured session notes at the end of every coding session. Triggers automatically when a session involves code changes — new files, bug fixes, refactors, features, config changes, or any modification to project files. Also triggers when the user says "write session notes", "log this session", "document what we did", "wrap up", or "end of session". If you made code changes during this session, use this skill before the conversation ends. Do not wait to be asked. --- # Session Notes At the end of every coding session where code was changed, write a structured session note capturing each individual change. This is how future sessions, reviewers, and the Loom dashboard understand what happened. ## When to Write Write session notes when any of these are true: - You created, modified, or deleted project files during this session - The user asks you to log, document, or wrap up the session - The conversation is ending and you made changes Do not write session notes for conversations that were purely discussion, planning, or Q&A with no file changes. ## Where to Write Session notes live in the project directory at `sessions/.md`. If the file doesn't exist, create it with the header template. If it exists, append a new dated session entry at the bottom. The project slug is the kebab-case project name — usually matches the directory name (e.g., `work-index-dashboard`, `cli-standardization`). ## Format Each session entry is a dated heading followed by one or more change entries. Each change has a label, a narrative, and four structured fields. ```markdown ## Session — YYYY-MM-DD ### - **What:** - **Why:** - **How:** - **Touches:** ``` ## Granularity This is the most important rule: **one entry per logical change.** A logical change is a new function, a new route, a new template, a config addition, a bug fix, or a refactor. If you'd explain it as a separate thing in a code review, it's a separate entry. The test: could someone read this single entry and understand what was changed without looking at the diff? If yes, the granularity is right. If they'd need to mentally decompose it into sub-changes, it's too coarse. **Too coarse** (don't do this): ```markdown ### Built the data layer Created vault reader, Trello client, and join layer. ``` **Right granularity** (do this): ```markdown ### Vault Frontmatter Reader Scans all .md files in the vault and extracts YAML frontmatter into VaultProject dataclasses... ### Trello REST Client Wraps the Trello board API with httpx... ### Join Layer Merges vault projects and Trello cards into a unified ProjectView... ``` ## Writing Quality The narrative is the most important part — it's what a human reads first. Write it as if you're explaining the change to a colleague who knows the project but wasn't in this session. Be specific about what was built, not just that something was built. For the structured fields: - **What** should be a single line, specific enough to be useful in a list - **Why** should state the actual motivation, not just "it was needed" - **How** should name the key functions, patterns, or libraries — enough that someone could find the relevant code without grepping - **Touches** should list every file that was created or modified, with `(new)` for new files ## File Header If creating the session notes file for the first time, use this header: ```markdown # — Session Notes Session log for the project. Each session is a dated heading with a list of changes. Each change has a label, narrative, and four structured fields (What, Why, How, Touches). --- ``` Then append the first session entry below the `---`. ## Reference See `references/example-session.md` for a complete example of a well-written session entry at the right granularity level.