From 04eec03f8461bcb9384a5acbc040bf98e1e93b78 Mon Sep 17 00:00:00 2001 From: herbygitea Date: Tue, 28 Apr 2026 00:08:00 +0000 Subject: [PATCH] Update session-notes-convention.md via n8n --- Tech/Projects/session-notes-convention.md | 148 ++++++++++++++++++---- 1 file changed, 124 insertions(+), 24 deletions(-) diff --git a/Tech/Projects/session-notes-convention.md b/Tech/Projects/session-notes-convention.md index 07747df..6998b19 100644 --- a/Tech/Projects/session-notes-convention.md +++ b/Tech/Projects/session-notes-convention.md @@ -1,6 +1,6 @@ --- project: session-notes-convention -type: reference +type: project-plan status: active path: Tech/Projects tags: @@ -8,40 +8,140 @@ tags: - documentation - claude-code - session-notes - - template + - workflow created: 2026-04-27 updated: 2026-04-27 --- -# Session Notes Template +# 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 -Copy this file into a new project at `sessions/.md` and -replace the placeholder values. ---- markdown -# — Session Notes +## Session — 2026-04-27 -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. +### 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. -Format for new entries: - -## Session — YYYY-MM-DD - -### +- **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) -- **What:** -- **Why:** -- **How:** -- **Touches:** +## Granularity Rule -Granularity rule: 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. ---- +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