Lint Operation#
Think of it like a Health Inspector for Your Sticky-Note Wall#
You've been adding notes to your wall for months. Some notes have arrows pointing to notes that no longer exist. Some notes sit alone in a corner with no arrows pointing to them at all — they're orphans, lost and forgotten.
The lint script is the inspector who walks the wall once a week and writes a report:
- Broken arrows — you wrote "see
[[Pasar Baru Spices]]" but there's no "pasar-baru-spices.md" note. The arrow points to a blank wall. - Orphans — you wrote a beautiful note about "Jakarta Flood Canal History" but nobody links to it and it's not in the index. It might as well be under the couch.
- Stale notes — notes labeled "updated: 2025-03-01". If today is 2026-07-07, that's 16 months old. Might be outdated. Needs a checkup.
- Missing labels — every note needs frontmatter. If a note lost its label tag, it's tagged as incomplete.
- Self-pointing arrows — note that says "see also:
[[:same note]]". Useless. The inspector flags it.
What the Inspector Checks#
| Check | What it finds | Why it matters |
|---|---|---|
| Broken links | [[:Dead Page]] with no matching file |
Following an arrow leads to nowhere → broken knowledge flow |
| Orphans | Pages no other page links to (except _index.md) |
Forgotten knowledge you can't discover by browsing |
| Stale >90d | updated date is >90 days old |
Information may be outdated, needs re-ingest |
| Missing frontmatter | title, tags, source, created, updated, status |
Confused notes without metadata are hard to find and trust |
| Self-links | Page linking to itself | A waste of an arrow |
The Actual Flow#
python3 ~/.hermes/scripts/llm-wiki-lint.py
Exit code 0 = healthy. 1 = issues found.
The Zen of Lint#
Lint is not punishment. It's preventive maintenance for your knowledge base. Like brushing your teeth — boring, but the alternative is rot.
- Run lint after every 5-10 ingests
- Always fix broken links immediately (they only get harder to trace)
- Orphans are okay if they're brand new — they'll get linked on the next ingest
- Stale pages that are still accurate? Just bump the
updateddate.
Remember: A wiki without lint is a garden no one weeds. At first it's fine. Then the weeds take over and you abandon it.