How to Lint the Wiki

A periodic health check. Run it when the wiki feels stale, after a batch of ingests, or whenever something seems off.

How to Trigger

lint
lint the wiki
run a lint pass

What Gets Checked

Check	What it catches
Pages on disk vs index.md	Pages that exist but aren’t catalogued, or entries pointing to deleted files
Broken [[cross-references]]	Links that don’t resolve to a real page
Orphan pages	Pages with no inbound links — likely disconnected from the wiki
Unresolved ⚠️ flags	Contradictions flagged during ingest that were never resolved
Missing ## See Also	Pages with no outbound links
Concepts mentioned but lacking a page	A term used across many pages that deserves its own entry

What Happens

1. Agent checks all pages in index.md exist on disk
2. Agent checks every [[cross-reference]] resolves
3. Agent reports findings as a checklist
4. Agent fixes what is clearly wrong (broken refs, formatting issues)
5. Agent flags ambiguous issues for you to decide
6. Agent logs the lint pass

Example Session

You:    lint

Agent:  Lint results:

        ✅ All 9 pages in index.md exist on disk
        ❌ fleet.md — 3 broken cross-references (missing wiki/elastic/ prefix) — fixed
        ❌ fleet.md — orphan page (no inbound links) — added to elastic-agent.md and kibana.md See Also
        ⚠️  No unresolved contradiction flags
        ✅ All pages have ## See Also sections

        2 issues fixed. Wiki is clean.
        Should I log this?

You:    yes

Inline Flags (set during ingest)

Flag	Meaning
> ⚠️ Contradiction: X conflicts with Y	New source contradicts an existing claim — needs resolution
> ❓ Unclear: what's uncertain	Source was ambiguous — needs a better source or follow-up

Lint will surface all unresolved ⚠️ flags so you can decide: update the page, discard the old claim, or leave it flagged.

Tips

• Run lint after every 5–10 ingests
• Use lint to find concepts worth turning into their own page: “sharding is mentioned in 4 pages but has no page”
• Lint can also suggest new sources to look for — gaps in your knowledge base
• After a restructure (renaming folders, moving pages), always lint immediately

See Also

• ingest-a-source — ingesting keeps lint busy
• query-the-wiki — querying can also surface gaps
• llm-wiki-pattern — lint as one of the three core operations