agentleFS
jamie8johnsonjamie8johnson/cqs/.claude/skills/groom-notes/SKILL.md

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.

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
  1. Very specific:

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

    line 14
  2. Very specific:

    Execute: Use cqs notes remove / cqs notes update CLI commands.

    line 31
  3. Distinctive:

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

    line 37
  4. Distinctive:

    Cross-check existing notes: Don't suggest notes that duplicate existing ones

    line 46
  5. Very specific:

    Execute: Use cqs notes add for each approved suggestion

    line 49
  6. Distinctive:

    Start with the built-in checker — it verifies every mention against the filesystem and index in one call:

    line 62
  7. Distinctive:

    Never remove or add notes without user approval

    line 72
  8. Distinctive:

    Keep notes that capture general lessons even if the specific code changed

    line 74
  9. Distinctive:

    When in doubt, keep the note — false negatives (missing a useful note) are worse than false positives (keeping a stale one)

    line 75
  10. Very specific:

    After grooming, suggest running cqs index to update the search index

    line 77

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.