lint

name

lint

description

Health-check an LLM wiki — a persistent, interlinked collection of markdown files — by scanning for contradictions, orphan pages, broken wikilinks, stale claims, missing cross-references, and knowledge gaps. Use this skill whenever the user wants to audit or maintain their wiki: "lint my wiki", "check my knowledge base for problems", "find contradictions in my notes", "what pages are orphaned", "audit my wiki", "clean up my wiki", "what's missing from my wiki", or any time they want a health report on a structured markdown knowledge store. Also trigger when the user mentions their wiki is getting messy, inconsistent, or hard to navigate.

Lint

Lint is the maintenance pass. As a wiki grows, it accumulates drift: contradictions between pages that were written at different times, pages nobody links to, wikilinks that point nowhere, claims that newer sources have superseded. Lint surfaces all of this so the user can decide what to fix.

The goal is a prioritized report, not an overwhelming list. Surface real issues with enough context to act on them, not pedantic noise.

Wiki location

Look for the wiki in this order:

1. A path the user explicitly specifies
2. A wiki/ subdirectory in the current working directory
3. The current working directory itself (if it looks like a wiki — has index.md or log.md)

If no wiki is found, tell the user.

Lint workflow

1. Build the page inventory

Start with index.md to get the full list of pages, then scan the actual directory to find any pages that exist on disk but aren't listed in the index. These are potential orphans or forgotten pages.

Also read schema.md to understand what conventions are expected — violations of schema conventions are themselves lint issues.

2. Check each category of issue

Work through these categories systematically. You don't need to read every page exhaustively before starting — scan for structural issues first (broken links, index mismatches), then do a deeper read for semantic issues (contradictions, stale claims).

Broken wikilinks

For every [[page-name]] reference in every page, check whether page-name exists as a file in the wiki. Collect all broken links with:

• The page that contains the broken link
• The broken link target
• Whether it looks like a typo, a renamed page, or a truly missing concept

Orphan pages

Pages that exist but are never linked to from any other page (and aren't in index.md). These have fallen off the knowledge graph and won't be found by navigating links. Note: index.md and log.md themselves are usually exempt.

Index gaps

Pages that exist on disk but are missing from index.md, or entries in index.md that don't correspond to actual files.

Contradictions

The most valuable lint check, and the hardest. Read pages that cover overlapping topics and look for direct conflicts: one page says X, another says not-X (or says something numerically or factually different). Note:

• Both pages involved
• What specifically contradicts
• Which source is likely more recent or authoritative (check log.md for dates)
• Whether this is a true contradiction or just different levels of nuance

Don't flag things as contradictions just because they're incomplete or differently scoped. A true contradiction is where both claims can't be true simultaneously.

Stale claims

Look for pages with concrete claims that may have been superseded: specific version numbers, "as of [year]", "currently", comparative statements like "X is the best available". Cross-reference with log.md — if a more recent ingest touched this domain, the older page might not have been updated.

Concept stubs

Pages that were created (often as wikilink targets) but never filled out — just a heading or a single line. These represent knowledge gaps where the wiki promised coverage it hasn't delivered. List them so the user knows what to prioritize ingesting next.

Missing cross-references

Pages that clearly discuss the same entity or topic as another page, but don't link to each other. These are connectivity gaps — the wiki knows things in two places that should know about each other. Flag the most obvious ones; don't enumerate every possible link.

3. Produce the lint report

Structure the report by severity/importance, not just by category. Issues that actively mislead (contradictions) are more urgent than cosmetic issues (missing links that exist).

# Wiki Lint Report — [date]

## Summary
X contradictions, Y broken links, Z orphan pages, N stubs
Overall health: [good / fair / needs attention]

## Critical: Contradictions
[List each contradiction with both pages and the specific conflict]

## Important: Broken wikilinks
[List broken links grouped by page]

## Important: Concept stubs
[Pages with minimal content — potential gaps in coverage]

## Housekeeping: Orphan pages
[Pages not linked from anywhere]

## Housekeeping: Index gaps
[Files not in index, or index entries with no file]

## Housekeeping: Missing cross-references
[Notable link gaps between related pages]

## Optional fixes
[Quick wins the user could act on now]

Offer to fix any of the housekeeping issues (broken links where the target is obvious, index gaps, adding cross-references) if the user wants. Contradictions and stale claims usually require human judgment to resolve.

4. Append to log.md

## [YYYY-MM-DD] Lint run
- Issues found: X contradictions, Y broken links, Z orphans, N stubs
- Fixed: [anything that was auto-fixed]
- Deferred: [anything flagged for human review]

Calibration

The most common mistake in linting is generating noise. An overwhelming list of minor issues is less useful than a focused list of things that actually matter.

Use judgment:

• A page with 3 sentences is a stub. A page with 2 paragraphs is probably fine even if it could be longer.
• A broken link to [[XYZ]] when xyz.md exists is a casing issue — note it but don't over-flag it.
• Two pages that approach a topic from different angles aren't contradicting each other unless the claims are mutually exclusive.

Prioritize things the user might act on today over an exhaustive audit.