Groom Notes

---
name: groom-notes
description: Review, prune, and suggest notes in notes.toml. Cleans stale notes and proposes new ones from recent changes.
disable-model-invocation: false
argument-hint: "[--warnings|--patterns|--all]"
---

# Groom Notes

Review all notes in `docs/notes.toml` — clean up stale ones and suggest new ones from recent work.

## Phase 1: Prune

1. **Parse notes**: Read `docs/notes.toml` and list all notes with their sentiment, text preview, and mentions.

2. **Identify candidates for removal**:
   - Notes that reference removed/renamed files (check with `Glob`)
   - Notes that contradict current code (e.g., "X doesn't work" when X was fixed)
   - Duplicate or near-duplicate notes covering the same topic
   - Notes about temporary issues that have been resolved
   - Notes with stale mentions (files that no longer exist)

3. **Present findings**: Show a summary of candidates grouped by reason:
   - **Stale**: References removed code or fixed issues
   - **Superseded**: Newer note covers the same ground
   - **Duplicate**: Multiple notes saying essentially the same thing
   - **Update mentions**: File paths that moved but lesson is still valid

4. **Get approval**: Present the list of proposed changes. Ask the user to confirm before making changes.

5. **Execute**: Use `cqs notes remove` / `cqs notes update` CLI commands. If the CLI isn't available, edit `docs/notes.toml` directly.

6. **Report**: Show before/after count and what was changed.

## Phase 2: Suggest

After pruning, scan for note-worthy events that aren't already captured:

1. **Check recent git history**: `git log --since="1 week ago" --oneline` (or since last groom)
2. **Look for surprise-worthy patterns**:
   - Bug fixes — what was the non-obvious cause? (sentiment: -0.5 or -1)
   - Refactoring lessons — what pattern worked or didn't? (sentiment: 0.5 or -0.5)
   - New features — any architectural decisions worth remembering? (sentiment: 0)
   - CI/tooling changes — any gotchas? (sentiment: -0.5)
   - Performance discoveries — unexpectedly fast or slow? (sentiment: 0.5 or -0.5)
3. **Cross-check existing notes**: Don't suggest notes that duplicate existing ones
4. **Present suggestions**: Show proposed notes with text, sentiment, and mentions
5. **Get approval**: User confirms which to add
6. **Execute**: Use `cqs notes add` for each approved suggestion

### What makes a good note

Notes capture **surprises** — things that broke predictions or would trip up a future session:
- "X looks like it should work but doesn't because Y" (negative surprise)
- "Doing X this way was unexpectedly effective" (positive surprise)
- "X and Y are coupled in non-obvious ways" (neutral observation)

**Not** good notes: routine changes, things obvious from code, activity logs.

## Staleness checks

Start with the built-in checker — it verifies every mention against the filesystem and index in one call:
```
cqs notes list --check --json
```
For anything it flags, confirm manually (Glob the file, `cqs "<symbol>" --name-only`) before proposing removal.

Cross-reference with git log — if a note mentions an issue number, check if that issue is closed.

## Rules

- Never remove or add notes without user approval
- Preserve the file header comments
- Keep notes that capture general lessons even if the specific code changed
- When in doubt, keep the note — false negatives (missing a useful note) are worse than false positives (keeping a stale one)
- Sentiment is DISCRETE: only -1, -0.5, 0, 0.5, 1
- After grooming, suggest running `cqs index` to update the search index