superhero-tech/super-brain/lint

Lint

Find what has rotted in the wiki, rank it, and hand the list to the human. Fixing is a separate decision.

Write the report in the language the wiki is written in.

How to invoke

• "Check the wiki", "run a lint", "health check"
• The monthly maintenance pass
• Before the human leans on the vault for something expensive

What this catches, and what it does not

Structural problems - missing citations, orphans, index drift, stale pages - it finds reliably, because they are mechanical.

Reasoning errors it finds badly. The model running this check shares its blind spots with the model that wrote the pages, so a clean report means the wiki is tidy, not that it is right. Say this out loud when you hand over a report with no errors.

How it works

1. Decide whether there is anything to check

Count the pages in 4-Knowledge/. Under ten, say there is not enough wiki to lint yet and stop. An empty report trains the human to ignore the next one.

2. Read everything

Read 4-Knowledge/index.md, then every wiki page. This is the one workflow that does not get to work from the index alone.

3. Classify what you find

Every finding names the page and says what to do about it. "Page X has issues" is not a finding.

On the source check: a citation is only checkable if the file it names sits in 5-Raw/. Match on the file name without its extension and compare character for character - a curly apostrophe in the archived file and a straight one in the citation are two different files, and neither looks wrong when you read it on its own. When a source really is absent, say which fix applies: archive the file, or correct the citation. Those are opposite moves and guessing wrong makes it worse.

4. Write the report

Save it to 4-Knowledge/lint-[YYYY-MM-DD].md:

---
title: Lint report
created: [YYYY-MM-DD]
pages_checked: [n]
---
 
# Lint report - [YYYY-MM-DD]
 
Checked [n] pages. Found [x] errors, [y] warnings, [z] notes.
 
## ERROR
 
-**[[Page Name]]** - contradicts [[Other Page]] on [claim]. `[source-a.md]` says X,
  `[source-b.md]` says Y. Neither is flagged.
-**[[Page Name]]** - cites `some-source.md`, not present in `5-Raw/`. The claim reads as
  documented and cannot be checked.
 
## WARN
 
-**[[Page Name]]** - orphan, nothing links here. Closest candidates: [[A]], [[B]]
 
## INFO
 
-"[concept]" appears on 4 pages and has none of its own. Worth writing.
-"[person or company]" is cited on 5 pages with no entity page. It has become a hub
  without one.
 
## Suggested next
 
1.[The single most valuable fix]
2.[Then this]
3.[Then this]

Rank the suggestions by what they unblock, not by severity order. An unranked report gets read once and never again.

5. Log it

Append a lint entry to 4-Knowledge/log.md. That file carries the format.

6. Hand it over

Report the counts and the top suggestion in the conversation, then stop. The human decides what gets fixed.

If they say go ahead, the fixes are a separate pass: make them, append an update entry to 4-Knowledge/log.md saying which pages changed and why, and refresh 4-Knowledge/index.md if any page description moved.

Self-check

• Every finding names a page and a next action
• Every cited source was checked against 5-Raw/, character for character
• The report is on disk at 4-Knowledge/lint-[YYYY-MM-DD].md
• 4-Knowledge/log.md has a lint entry with the counts
• The suggestions are ranked
• A clean report came with the caveat about what this check cannot see

Hard constraints

• Lint reports, it does not repair. Pages change after the human agrees, never during the check.
• Sources in 5-Raw/ are read-only. A contradiction between a page and its source is a finding about the page.