| name | wiki-lint |
| description | Run health checks on the vault. Combines structural checks (broken wikilinks, orphan pages, missing frontmatter fields, stale `modified` dates, tag synonyms, convergence debt in `raw/`, asset coverage) with semantic checks (contradiction detection across pages claiming the same fact). Use on request — "lint the wiki" / "check wiki health" — weekly or per-sprint, or after bulk ingestion of new raw sources. |
| license | MIT |
wiki-lint
⚠️ Not yet shipped in v2.0.0.dev. This skill is invoked via
wiki run wiki-lint, and wiki run is a stub in v2.0.0.dev: it
prints wiki run: not yet implemented (v2 migration in progress, see RFC-0001). and exits non-zero (see
llm_wiki_kit/cli.py:_cmd_run). The operation runner lands in
Phase D of the v2 migration. Until then, treat this SKILL.md as the
design spec — the structural checks it describes are not wired
up. Tracked under retro-review concern C7 (issue #23).
Comprehensive health checks. Some are deterministic (Python scripts);
some are semantic (you decide). Run the deterministic ones first —
they're cheap and surface most of what's wrong.
When to load this skill
- On request: "lint the wiki", "check wiki health", "run a lint".
- Scheduled: once a week, or per-sprint, by the user's request.
- After bulk ingestion of new raw sources.
- Before a big synthesis pass (a digest, a quarterly review) — start
from a clean baseline.
What the lint covers
| Check | Mode | Cost |
|---|
| Missing required frontmatter | Script | Cheap |
| Tag hygiene (synonyms, typos) | Script + your review | Cheap |
| Broken wikilinks | Script | Cheap |
| Orphan pages (no inbound links) | Script | Cheap |
Stale modified (> N days) | Script | Cheap |
| Asset coverage (assets without companion page) | Script | Cheap |
Convergence debt (raw/ files no page references) | Script | Cheap |
| Contradiction detection | You read & reason | Expensive |
Order of operations
-
Acquire the lock (lint may write a report). Load
skills/wiki-lock/SKILL.md.
-
Run the structural checks. A single command:
wiki run wiki-lint --output log/lint-$(date +%Y-%m-%d).md
Reads the vault, emits a markdown report, journals a lint.run
event with the issue count.
-
Read the report. Section by section: frontmatter, links,
orphans, staleness, assets, convergence debt. Summarize what
you found into chat in 5-8 bullets.
-
Run contradiction detection only if requested. It's
token-heavy — don't initiate it unless the user asks or the
structural report flagged a specific topic to investigate.
-
Auto-fix what's safe (see below) after the user confirms.
-
Surface what isn't auto-fixable as a list of pages and what
needs to happen.
-
Release the lock.
Contradiction detection (the expensive one)
For a topic or domain the user names:
- Use
wiki-search to find pages tagged with the topic.
- Read the synopsis of each (depth 1).
- Identify pages that make claims about the same entity or
decision.
- Read those pages in full (depth 2).
- Quote the conflicting claims back to the user with page
references.
Don't decide the contradiction. The user owns reconciliation;
you surface it.
Auto-fix (with confirmation)
After the user reviews the report, these are safe to fix
automatically — but always ask first:
- Add a missing
> [!warning] Outdated callout to a stale page.
- Update a stale page's
modified date (only if you also touched
the content in this session).
- Backfill a missing
provenance field (default to mixed for
pages of unknown origin; ask if there's any doubt).
- Generate a missing
## Synopsis section from existing content.
These always require user review — never auto-fix:
- Resolving contradictions.
- Merging synonym tags (one canonical tag, retag every page).
- Archiving orphan pages (the orphan may be a stub waiting for a
link).
- Deleting convergence debt (the source might be intentionally
unprocessed).
Reading the report
The report is a markdown file the user reads. Summarize it in chat:
Lint summary, 2026-05-15:
- 3 pages missing
provenance — fixable, with confirm.
- 7 broken wikilinks — need user review (mostly typos in target
names).
- 12 orphan pages — most look intentional, but
efforts/projects/x.md
should probably link to people/x.md.
- 2 stale pages (> 90 days) flagged as
active — confirm they
really are.
- 0 contradictions (not run; ask if you want me to).
Don't dump the whole report into chat. The user can open it.
Output
- The report file at
log/lint-YYYY-MM-DD.md.
- A
lint.run event in the journal with the issue count and status
(ok, issues, error).
- A line in
log/changelog.md summarizing what you ran.
