chemenu/instructions/wiki-lint/SKILL.md

name, description

name	description
wiki-lint	Health-check the LLM wiki - broken links, orphan pages, uncovered raw files, stale claims, duplicated rules, missing cross-references. Use when the user says "lint the wiki", "health-check the wiki", or periodically every 10 sources per the Maintenance Schedule.

Wiki Lint

Purpose: Health-check and maintain the wiki.

Trigger: User requests a lint, or tools/wikitool log status reports the "every 10 sources" threshold reached - wiki-ingest's last step checks it after every publish, so the count is never something an agent has to remember.

Before the first wikitool call: instructions/session-setup.md.

Run checklist

Copy this block into your first reply of the pass and tick each line as you reach it. Steps 3-6 are pure judgment: nothing errors when they are skipped, and a pass that quietly ran only its mechanical half looks exactly like a complete one.

- [ ] 1. Structural scan
- [ ] 2. Raw coverage
- [ ] 3. Contradictions (judgment)
- [ ] 4. Stale claims (judgment)
- [ ] 5. Missing pages (judgment)
- [ ] 6. Duplicated rules (judgment)
- [ ] 7. Repair what is mechanical
- [ ] 8. Verify the stack
- [ ] 9. Rebuild, write the report, carry its findings out

Steps

1. Structural scan.

   tools/wikitool lint
   

   No flags: prints the sections that found something, writes the full report to reports/Lint Report <YYYY-MM-DD>.md, and names that path. This deterministically finds unreadable frontmatter, broken wikilinks, dangling frontmatter references, orphan pages, catalog drift, missing fields, duplicate titles, filename/title mismatches, broken raw_files: references, raw files claimed by more than one source page, invalid type paths, schema failures, citation/frontmatter drift, and edges whose label is missing, not authorised by the source collection, or redundant beside a specific label on the reverse direction. Do not re-derive any of it by reading pages.

   The Redundant see-also section is the one that looks mechanical and is not - do not clear it under step 7. It names a see-also edge standing beside a specific label on the reverse direction, and the obvious repair destroys the thing worth keeping: xref remove clears the reference in both directions (see tools/CONTRACT.md), so removing the weak edge takes the labelled one with it and the pair ends up saying nothing at all. Either relabel the weak edge to something true with xref add, which only ever touches the source page, or leave it and report it at step 9. Clearing a batch of these is a planned corpus sweep with its own run, never a reaction inside a lint.

   To see more of the report, read the file - never run lint again. A second run costs a budget slot and re-measures a corpus that has not changed. The file at step 9 overwrites this one, so what ships records the wiki's final state rather than its state on arrival.

2. Raw coverage.

   tools/wikitool sources coverage
   

   Flag un-ingested raw files and legacy directory/URL-only source pages as candidates for a future ingest.

3. Contradictions (judgment). Look for conflicting claims across pages. Note which is more recent or better supported, and propose a resolution to the user rather than picking one silently.

4. Stale claims (judgment). Claims unconfirmed for >6 months, superseded by a newer source, or naming an outdated version. tools/wikitool search --field 'modified<<date>' --sort modified finds candidates cheaply.

5. Missing pages (judgment). Subjects mentioned across several sources, or with many outbound links, that have no page of their own.

6. Duplicated rules (judgment). AGENTS.md invariant 8 is "one rule, one place", and it is deliberately not machine-checked - prose duplication is a judgment call. Check whether a normative rule has been restated in a second contract, skill or instruction. If so: decide which location is canonical, and replace the others with a link. Two copies of a rule is how they start disagreeing.

7. Repair what is mechanical. A dangling frontmatter reference is either a page that should exist (tools/wikitool new ...) or a reference that should not (tools/wikitool xref remove --a "<Page>" --b "<Missing>"). A title that changed is tools/wikitool rename - see instructions/page-lifecycle.md. Never hand-edit a frontmatter array to clear one.

8. Verify the stack.

   tools/wikitool docs verify
   tools/wikitool instructions verify
   

   docs verify catches command/contract drift and ignore rules that would silently un-publish content; instructions verify catches a skill copy that drifted from its source and an instruction nothing references.

9. Rebuild, write the report, carry its findings out.

   tools/wikitool sources rebuild-index
   tools/wikitool index rebuild
   tools/wikitool lint
   

   Then fill in that report's "Semantic Review" section with the findings from steps 2-6.

   The report is gitignored and is not a wiki page. Its structural half is recomputable; the semantic review is not, so it has to leave reports/ before the pass ends. Findings that change a page go into the page; a one-line summary of the pass goes into the audit trail:

   tools/wikitool log append --op lint --title "<date>" --body "<summary>"
   

   A pass whose conclusions exist only in reports/ has lost them. There are no old reports to retire - nothing there was ever committed.

Decision points

• Publish? Lint does not auto-publish. Run tools/wikitool publish only if asked.
• Bulk fixes touched 10+ files? Expected for a lint pass: publish exits 42. Show the user its output and stop; see instructions/gates.md. Consider --path batches instead.
• The gate or loop-breaker keeps tripping? That is a signal to stop and re-plan with the user, not to pass --override-budget. A full pass should land in roughly 20-35 calls.

wikitool commands used

lint, search, sources coverage, xref add, xref remove, rename, new, docs verify, instructions verify, sources rebuild-index, index rebuild, log append, publish (only if asked)

Deliberately absent: rm - a lint pass never deletes a page, and instructions/page-lifecycle.md is where a deletion belongs. log status - it decides this skill's trigger, but wiki-ingest's last step is what runs it.

Output

A lint report with findings and recommendations, its semantic half carried into the pages and the log.

Example trigger: "Lint the wiki"