Merge branch 'docs-audit'

README.md

@@ -0,0 +1,87 @@
+# session-notes-skill
+
+A Claude Code skill that **enforces** structured session-note
+documentation at the end of every coding session.
+
+The skill doesn't generate code or transform files. It teaches the agent
+*what* to write, *when*, and at *what granularity* — so each meaningful
+change in a session lands as a separate, parseable entry in the
+project's `sessions/<slug>.md` file.
+
+Designed to pair with the Loom dashboard (the work-index-dashboard
+reader) and with project-local review workflows that scan session notes
+for context.
+
+## What it does
+
+- **Triggers automatically** at end-of-session when the agent has made
+  file changes. Also triggers on explicit prompts: "write session
+  notes", "log this session", "document what we did", "wrap up",
+  "end of session".
+- **Enforces granularity:** one entry per logical change. New function,
+  new route, new template, new config setting, bug fix — each get their
+  own entry. The skill spec calls out the "combine everything into one
+  paragraph" anti-pattern and provides side-by-side too-coarse vs.
+  right-granularity examples.
+- **Writes to the project, not the skill:** the agent appends entries
+  to `sessions/<slug>.md` in the project it's currently working in.
+  This skill repo stores no session data.
+
+## Install
+
+The skill ships as a zip: `session-notes.skill`.
+
+**From the packaged `.skill`:**
+
+```bash
+cp session-notes.skill ~/.claude/skills/
+```
+
+**From the source tree** (for development):
+
+```bash
+ln -s "$(pwd)/session-notes" ~/.claude/skills/session-notes
+```
+
+Once installed, the skill self-loads on every session where the agent
+modifies files. No flags or `/commands` needed.
+
+## How agents use it
+
+When the skill fires, the agent:
+
+1. Reads `SKILL.md` (always loaded — the format + rules).
+2. Loads `references/example-session.md` on demand to calibrate the
+   granularity if the changes are non-trivial.
+3. Appends entries to `sessions/<project-slug>.md` in the current
+   project. Creates the file if it doesn't exist.
+
+## Granularity, restated
+
+> One entry per logical change. If it would be a separate item in a
+> code review, it's a separate entry here.
+
+This is the rule the skill is built around — see
+`session-notes/references/example-session.md` for what it looks like
+in practice.
+
+## Repo layout
+
+```
+session-notes-skill/
+  session-notes/
+    SKILL.md                     # Skill definition (triggers + format + granularity rule)
+    references/
+      example-session.md         # Calibration examples (good vs. too-coarse)
+  session-notes.skill            # Packaged zip (regenerate after edits)
+  sessions/
+    session-notes-skill.md       # The skill dogfoods itself here
+  CLAUDE.md                      # Agent notes
+  README.md                      # This file
+```
+
+## Packaging a release
+
+```bash
+cd session-notes && zip -r ../session-notes.skill SKILL.md references/
+```