1f7a85b7d1
Skill that triggers at the end of every coding session where files changed. Enforces structured session notes with label, narrative, and four fields (What, Why, How, Touches) at one-entry-per-logical-change granularity. Includes reference examples from the Loom project and review-ready CLAUDE.md with key patterns documented.
122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
---
|
|
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/<project-slug>.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
|
|
|
|
### <Change Label>
|
|
<Narrative — what was done and why, in plain English. 2-4 sentences
|
|
that explain the change to someone who hasn't seen the code.>
|
|
|
|
- **What:** <one-line summary of the change>
|
|
- **Why:** <the motivation — what problem or need drove this>
|
|
- **How:** <implementation approach — key functions, patterns, libraries used>
|
|
- **Touches:** <files modified, with (new) for new files>
|
|
```
|
|
|
|
## 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
|
|
# <Project Name> — Session Notes
|
|
|
|
Session log for the <project-slug> 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.
|