groom-notes
Skill18 starsChanged 5 months agoMITView on GitHub
Review, prune, and suggest notes in notes.toml. Cleans stale notes and proposes new ones from recent changes.
In this repository22 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- archeoSkill
- auditSkill
- before-editSkill
- boundary-probeSkill
- check-my-workSkill
- cqs-batchSkill
- cqs-bootstrapSkill
- cqs-planSkill
- cqsSkill
- cqs-verifySkill
- docs-reviewSkill
- idleSkill
- investigateSkill
- landSkill
- migrateSkill
- prSkill
- recall-gateSkill
- reindexSkill
- releaseSkill
- troubleshootSkill
- update-tearsSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Parse notes: Read docs/notes.toml and list all notes with their sentiment, text preview, and mentions.
- Very specific: line 31
Execute: Use cqs notes remove / cqs notes update CLI commands.
- Distinctive: line 37
After pruning, scan for note-worthy events that aren't already captured:
- Distinctive: line 46
Cross-check existing notes: Don't suggest notes that duplicate existing ones
- Very specific: line 49
Execute: Use cqs notes add for each approved suggestion
- Distinctive: line 62
Start with the built-in checker — it verifies every mention against the filesystem and index in one call:
- Distinctive: line 72
Never remove or add notes without user approval
- Distinctive: line 74
Keep notes that capture general lessons even if the specific code changed
- Distinctive: line 75
When in doubt, keep the note — false negatives (missing a useful note) are worse than false positives (keeping a stale one)
- Very specific: line 77
After grooming, suggest running cqs index to update the search index
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Groom Notes
Review all notes in docs/notes.toml — clean up stale ones and suggest new ones from recent work.
Phase 1: Prune
- Parse notes: Read
docs/notes.tomland list all notes with their sentiment, text preview, and mentions. - 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)
- Notes that reference removed/renamed files (check with
- 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
- Get approval: Present the list of proposed changes. Ask the user to confirm before making changes.
- Execute: Use
cqs notes remove/cqs notes updateCLI commands. If the CLI isn't available, editdocs/notes.tomldirectly. - Report: Show before/after count and what was changed.
Phase 2: Suggest
After pruning, scan for note-worthy events that aren't already captured:
- Check recent git history:
git log --since="1 week ago" --oneline(or since last groom) - 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)
- Cross-check existing notes: Don't suggest notes that duplicate existing ones
- Present suggestions: Show proposed notes with text, sentiment, and mentions
- Get approval: User confirms which to add
- Execute: Use
cqs notes addfor 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 --jsonFor 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 indexto update the search index
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

