| name | wiki-lint |
| description | Run a health check on the wiki. Finds orphan pages, dead wikilinks, stale sources, contradictions, index gaps, missing concept pages, and unlinked entities. Produces a lint report and asks before making any changes. Triggers on: wiki-lint, lint the wiki, wiki health check, check the wiki, wiki audit, find orphans, wiki maintenance.
|
| allowed-tools | Read Write Edit Glob Grep Bash |
wiki-lint
Read skills/wiki-schema/SKILL.md fully before proceeding.
Invoke with: /wiki-lint
Step 1 — Resolve VAULT_PATH
Vault path: ~/obsidian_vault by default; set VAULT_PATH to override. WSL users with a Windows-side vault must set VAULT_PATH explicitly (e.g. /mnt/c/Users/<name>/obsidian_vault).
Step 2 — Enumerate all wiki pages
First verify the wiki directory exists:
[ -d "wiki" ] || { echo "Wiki not initialised — run /wiki-ingest to create the first page."; exit 0; }
find "wiki" -name "*.md" \
-not -name "_index.md" \
-not -name "_log.md" \
-not -name "hot.md"
Also read wiki/_index.md for the catalog (skip if absent) and
wiki/_manifest.json for ingest history (skip if absent).
Step 3 — Run all lint checks
Work through each check. Collect findings before writing the report.
Check 1 — Orphan pages
A wiki page is an orphan if:
- No other wiki page contains a
[[wikilink]] pointing to it, AND
- It is not listed in
_index.md
Scan every wiki page body and _index.md for wikilinks. Any page not referenced by
either is an orphan.
Severity: medium (orphans may be intentional seeds — do not auto-delete).
Check 2 — Dead links
For every [[wikilink]] found in wiki page bodies and frontmatter related: lists:
check that a file with a matching basename exists somewhere in the vault.
find "<VAULT_PATH>" -name "<linked-title>.md"
Severity: high — dead links silently break the wiki graph.
Check 3 — Stale sources (Layer 1 files changed since ingest)
For every Layer 1 file recorded in _manifest.json:
- Check if the file still exists.
- Compute its current hash:
md5sum "<filepath>" | cut -d' ' -f1
- Compare to the manifest hash.
If hash differs: the source has changed since it was ingested. The wiki pages derived
from it may be outdated.
Severity: medium — flag for re-ingest, do not auto-re-ingest.
Check 4 — Contradictions
Scan all wiki page bodies for > [!warning] callouts containing "contradiction" or
"conflict". These were flagged during ingest and need human resolution.
Severity: high — unresolved contradictions mean the wiki has conflicting facts.
Check 5 — Index gaps
For every .md file found in wiki/concepts/, entities/, decisions/,
patterns/, and sources/: check that it appears as a row in _index.md.
Pages present on disk but absent from the index are invisible to wiki-query Path B.
Severity: high — add missing entries to _index.md.
Check 6 — Missing concept pages
Scan all wiki pages for terms that:
- Are used as
[[wikilinks]] in 3 or more distinct pages, AND
- Do not resolve to an existing page anywhere in the vault.
These are concepts the wiki references repeatedly but has never documented.
Severity: medium — create stub concept pages with wiki-status: seed.
Check 7 — Unlinked entities
Scan all wiki page bodies for the names of known entities (read the entities/ directory
for canonical names). When an entity name appears as plain text (not a wikilink), flag it.
Severity: low — informational; the wiki is navigable without these links but they
improve the graph.
Step 4 — Write the lint report
Create wiki/lint-report-YYYY-MM-DD.md:
---
type: meta
title: "Lint Report YYYY-MM-DD"
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags:
- doc
wiki-status: stable
---
# Wiki Lint Report — YYYY-MM-DD
## Summary
- Pages scanned: N
- High severity issues: N
- Medium severity issues: N
- Low severity issues: N
- Safe to auto-fix: N
## Check 1 — Orphan Pages [severity: medium]
- [[concepts/Orphaned Page]]: no inbound links. Suggested fix: link from [[related page]]
or confirm intentional isolation.
## Check 2 — Dead Links [severity: high]
- [[Missing Page]]: referenced in [[concepts/Source Page]] but does not exist.
Suggested fix: create stub page or remove wikilink.
## Check 3 — Stale Sources [severity: medium]
- `Meetings/MGD/2026-04-10 MCP Planning.md`: hash changed since ingest on 2026-04-10.
Suggested fix: run `/wiki-ingest Meetings/MGD/2026-04-10 MCP Planning.md`
## Check 4 — Unresolved Contradictions [severity: high]
- [[concepts/MCP Server]]: contains `> [!warning]` contradiction callout. Needs review.
## Check 5 — Index Gaps [severity: high]
- `wiki/concepts/New Concept.md`: not listed in _index.md.
Suggested fix: add index row (safe to auto-fix).
## Check 6 — Missing Concept Pages [severity: medium]
- "gRPC": referenced as [[gRPC]] in 4 pages but no concept page exists.
Suggested fix: create `wiki/concepts/gRPC.md` with wiki-status: seed.
## Check 7 — Unlinked Entities [severity: low]
- "John Brown" appears as plain text in [[concepts/MCP Server]] — not wikilinked.
Suggested fix: replace with [[entities/John Brown]].
Step 5 — Ask before fixing
Show the report summary. Ask:
Found: N high, M medium, L low severity issues.
Safe to auto-fix (index gaps, seed stubs): N items.
Fix safe items automatically? [yes / no]
Fix all issues interactively? [yes / no]
Safe to auto-fix without asking:
- Adding missing
_index.md rows for existing pages (Check 5)
- Creating seed stub pages for missing concepts with 3+ references (Check 6)
Requires human decision before fixing:
- Deleting orphan pages (might be intentional)
- Resolving contradictions (requires judgment)
- Deciding whether to re-ingest stale sources
Step 6 — Append to _log.md
## [YYYY-MM-DD] lint | health check — N pages, H high, M medium, L low
- Report: [[lint-report-YYYY-MM-DD]]
- Auto-fixed: <N items or "none">
Step 7 — Update hot.md
Note the lint run, issue counts, and any fixes applied in ## Recent Changes.
