34a268d8dc
Two-layer structure: Sources (raw notes) + Wiki (compile output) Four domains: Dev (40), Venture (3), Homelab (23), Reference (0) Includes CLAUDE.md spec, index pages at all levels, compile log Co-Authored-By: Lovebug <lovebug@herbylab.dev>
150 lines
5.0 KiB
Markdown
150 lines
5.0 KiB
Markdown
---
|
|
created: 2026-04-27
|
|
path: Sources/Dev
|
|
project: session-notes-convention
|
|
status: active
|
|
tags:
|
|
- pbs
|
|
- documentation
|
|
- claude-code
|
|
- session-notes
|
|
- workflow
|
|
type: project-plan
|
|
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 |