notes-heartbeat
Skill1 starsChanged 3 months agoMITView on GitHub
Heartbeat check over $VAULT. Runs deterministic scans and fixes only what a script proved wrong: broken links, malformed fences, bad frontmatter, paths that no longer resolve, etc. Use when asked to check, audit, or clean up the notes or the vault, to rebuild the indexes, or to look for stale info in the notes. Judgment work belongs to sleep.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-sourceSkill
- analyze-videoSkill
- archive-projectSkill
- clean-projectSkill
- code-standardsSkill
- global-heartbeatSkill
- map-projectSkill
- researchSkill
- resolve-projectSkill
- sleepSkill
- test-projectSkill
The file
Files
notes-heartbeat
python3 $VAULT/.scripts/health.pyEverything this skill acts on is something the script proved. Nothing here decides whether a note deserves to exist, whether two notes should merge, or what a topic should now say. That is sleep, and mixing the two is how a five-minute check turns into an hour of rewriting.
One section at a time when you want it: health.py links, or prose, format, paths, meta, dupes, graph.
What each finding means and what to do
| Finding | Fix |
dangling | the target was deleted: repoint at whatever superseded it. Marks a note worth writing: leave it. |
fence | a ``` opener sitting mid-line opens nothing, so the block below renders as prose and its brackets parse as links. Move it to column 1. |
em-dash | rewrite per $VAULT/.claude/rules/voice.md. sources/ is excluded from the scan, since that is the source's own text. |
scar | edit-history narration inside a note. Fold the surviving conclusion in and delete the marker, per $VAULT/.claude/rules/notes.md. |
meta | add the field, or rename the file so name matches it. |
path | check whether the thing moved or died, then fix or cut the sentence. Eyeball first: a path containing a space truncates at the space and reads as missing when it exists. |
unlinked | a note's name in plain prose with no wikilink. Usually just wrap it. |
dupe | two sources/ files whose bodies or filenames overlap enough to be one document. Never a fix here: sleep's dupe agents read both and judge. |
graph | never a fix, only a number. Falling out-degree is the signal sleep acts on. |
reindex.py runs first and its own reports (orphan, unfolded, adrift, ambiguous, dangling) print above the health output. Same rule: fix the mechanical ones, hand the rest up.
Where this stops
Four findings look mechanical and are not. Each goes to sleep rather than getting decided here:
unlinkedin bulk. One or two are typos. Thirty means the graph needs a pass, not thirty edits.scarthat is load-bearing. "CGSSetWindowShapeis proven dead" reads like a correction scar and is a fact worth keeping. Deleting it re-opens a closed question.pathinside an archived project's note. The path is gone because the project is. Whether the note still earns its place is a prune decision.- Anything suggesting two notes are one note. Merging is
sleep's.
Rules
- Report, then fix. Never rewrite meaning. A repair changes syntax, a path, a field, or a link. Changing what a note claims is out of scope even when the claim looks wrong; that is a finding to raise.
compass/takes repairs and nothing else. A dangling wikilink or a broken fence in a compass note is fixable withEditlike anywhere else. Its claims are not, and aWriteagainst it is blocked by hook.compass/notes never report asorphan: they sit above the graph and route down.- Return the count.
health.pyopens with the note total split by folder, and that line leads the report every run, before any finding. It counts real notes only:instructions/, the*-spec.mdsymlinks, generated indexes, and the dot-folders are all out.reindex.pycounts differently and prints its own line above; when the two disagree, this one is the vault's size. - Note deletion owned by
.agent-instructions/pruning.mdand needs approval. - Re-run
health.pyat the end. A repair that introduced a dangling link is the common way this goes wrong.
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.