---
project: session-notes-convention
type: project-plan
status: active
path: Tech/Projects
tags:
  - pbs
  - documentation
  - claude-code
  - session-notes
  - workflow
created: 2026-04-27
updated: 2026-04-27
---
# Session Notes Convention

A standardized format for documenting coding session changes at the
individual-change level. Provides structured context for debugging,
deployment, agent handoffs, and independent code review.

## Why

Coding sessions produce changes that are hard to reconstruct after the
fact. Without a structured log, answering "what changed and why" requires
reading diffs, grepping commit messages, or asking the agent that did the
work. Session notes close that gap by capturing each logical change with
enough detail that a human or agent can understand it without looking at
the code.

This convention also provides the context layer for future tooling —
specifically an independent code review skill that needs to know what
was intended in order to evaluate what was produced.

## Consumers

The same session note serves multiple consumers:

- **Travis** — "what happened" for debugging and deployment
- **Loom dashboard** — session activity per project, loose thread scanning
- **Code review skill** — intent vs. implementation comparison
- **Next agent** — handoff context for what was done and what's next

## Format

Each session note file lives in the project directory (e.g.,
`sessions/.md`). The file has a header with format
instructions, then dated session entries. Each entry is a list of changes.

Each change has:

- **Label** — short title (the `###` heading)
- **Narrative** — free text describing what was done and why, in plain
  English
- **What** — one-line summary
- **Why** — the motivation
- **How** — implementation approach, key functions/patterns
- **Touches** — files modified

### Example Entry

markdown
## Session — 2026-04-27

### Trello REST Client
Wraps the Trello board API with httpx. Fetches lists and cards, groups
cards by label name (which is the project slug). Includes in-memory cache
with configurable TTL so the dashboard doesn't hit Trello on every page
load.

- **What:** `TrelloClient` class with card grouping and TTL cache
- **Why:** Dashboard needs live Trello card state joined to vault data
- **How:** httpx.Client with 15s timeout. `_fetch_all()` populates cache
  dict with lists and cards. `get_cards_by_project()` groups cards by
  label name. `refresh()` invalidates cache.
- **Touches:** data/trello.py (new)


## Granularity Rule

One entry per logical change — a new function, a new route, a new
template, a config addition, or a bug fix. If you'd explain it as a
separate thing in a code review, it's a separate entry.

Don't roll multiple changes into one entry just because they were part
of the same feature. The test: could someone read this entry and
understand what was changed without looking at the diff?

## CLAUDE.md Integration

Each project's CLAUDE.md should include a Session Notes section at the
bottom pointing to the session notes file and restating the granularity
rule:

markdown
## Session Notes

After each coding session, append a session entry to
`sessions/.md` in this project folder.
See that file for the format convention and existing entries.

Granularity: one entry per logical change. A new function, a new route,
a new template, a new config setting, or a bug fix each get their own
entry. Don't combine multiple changes into one entry. If it would be a
separate item in a code review, it's a separate entry here.


## Rollout

### Phase 1 — Convention documented
- [x] Define session note format (label, narrative, what/why/how/touches)
- [x] Define granularity rule
- [x] Validate format against real project (Loom work-index-dashboard)
- [ ] Create session note template file

### Phase 2 — Apply to existing projects
- [ ] Add session notes section to Loom CLAUDE.md (done by Lovebug)
- [ ] Retrofit session notes for any other active Claude Code projects
- [ ] Add convention to Claude Code skill or global CLAUDE.md so all
      new projects pick it up automatically

### Phase 3 — Tooling integration
- [ ] Loom dashboard reads session notes (already v2 of Loom)
- [ ] Code review skill uses session notes as reviewer context
- [ ] Evaluate whether session notes should auto-generate from git
      diff + agent summary

## Open Questions

- Should the session notes file live at `sessions/.md` in the
  project repo, or in the vault alongside the project plan?
- Should there be a global CLAUDE.md convention (e.g., in `~/.claude/`)
  that applies the session notes rule to all projects automatically?
- Phase 3: should session notes be agent-written only, or should there
  be a manual entry path too?

## Success Criteria

The convention is working when:
- Lovebug produces session notes at the right granularity without
  being reminded
- Travis can open a session note and understand what changed without
  reading the diff
- The code review skill can use session notes as context and produce
  better reviews than a naked diff alone


...sent from Jenny & Travis

...sent from Jenny & Travis