geronimo-iia/llm-wiki-skills/lint

Lint

Structural audit of the wiki. Find quality issues, report them, and offer fixes.

Deterministic checks (engine)

Start every audit by running the engine lint tool. These checks are index-based, deterministic, and fast.

For small wikis (< 200 pages):

wiki_lint()

For large wikis (200+ pages): use the three-phase sequence to avoid oversized responses.

Phase 1 — triage (counts only, no findings):

wiki_lint(summary: true)

Returns by_rule counts. Identify which rule has the most findings before requesting the full list.

Phase 2 — scope (single rule, optional subtree):

wiki_lint(rules: "missing-fields", path_prefix: "nrg-architecture/studies")

Phase 3 — paginate only if the scoped result is still large:

wiki_lint(rules: "missing-fields", path_prefix: "nrg-architecture/studies", page_size: 100)

Pass the returned next_cursor to the next call until has_more is false.

This returns a JSON report with findings grouped by rule:

Run a subset of rules:

wiki_lint(rules: "orphan,broken-link")

Run structural rules only (graph-based, O(n+e) for articulation-point and bridge, O(n²) for periphery — skipped when local_count > graph.max_nodes_for_diameter):

wiki_lint(rules: "articulation-point,bridge,periphery")

Filter to errors only (CI-suitable):

wiki_lint(severity: "error")

Target a specific wiki:

wiki_lint(wiki: "research")

An empty findings array means the wiki is clean for these rules. error findings block CI (llm-wiki lint --severity error exits non-zero).

Schema integrity

Validate all schema files for correctness and index compatibility:

wiki_schema(action: "validate")

Checks: valid JSON Schema, x-wiki-types presence, alias resolution, base schema invariant (default type requires title and type), and full index compatibility.

Validate a single type:

wiki_schema(action: "validate", type: "<type>")

Edge target type validation

Use dry-run ingest to check for edge target type mismatches without modifying the index:

wiki_ingest(path: "<path>", dry_run: true)

The engine reads x-graph-edges from the type's schema and warns when an edge target has the wrong type.

Judgment-based checks (skill layer)

These require reasoning and stay in the skill — they cannot be reduced to an index query.

Structural orientation

For structural health — pages and links whose removal would disconnect the graph:

wiki_lint(rules: "articulation-point,bridge,periphery")

For a full-wiki page overview before gap analysis, use format: "llms":

wiki_list(format: "llms")

This covers the full wiki grouped by type with summaries — one call, no pagination.

Empty sections

wiki_list(type: "section", page_size: 50)

For each section, check if any pages exist under that slug prefix.

Missing stubs

Referenced slugs that don't exist and have not been caught by broken-link (e.g. intentional forward references). These are candidates for new pages — create stubs or remove the dead reference.

Untyped sources

Pages with a generic or missing type that appear to be source summaries should use a specific source type (paper, article, documentation, etc.). Requires judgment: is this page acting as a source?

Draft audit

wiki_stats()

The status facet (keyword FAST field) shows the distribution (e.g. active: 40, draft: 3). Review draft pages: are they progressing, abandoned, or placeholders?

Under-linked pages

wiki_suggest(slug: "<slug>", limit: 10)

Pages with many high-score suggestions are likely under-linked. Requires relevance judgment — don't link for graph density.

Report findings

Present findings grouped by category, leading with wiki_lint output:

• Engine findings — orphans, broken links, missing fields, stale, unknown types, articulation points, bridges, peripheral pages
• Schema issues — invalid schemas, field conflicts
• Edge type mismatches — wrong target types on graph edges
• Empty sections — sections with no children
• Missing stubs — referenced pages that don't exist
• Untyped sources — source pages without specific types

Fix issues

For each category:

• Broken links — remove dead references or create the missing pages
• Broken cross-wiki links — run wiki_spaces_list() to confirm the wiki name; if the target wiki is intentionally not mounted (referencing a planned future space), the Warning can be acknowledged and ignored; otherwise fix the wiki name or mount the space
• Orphan pages — add a [[slug]] reference from a related page, or link from a section or index page
• Missing fields — open the page and add the required frontmatter field for its type; use wiki_schema(action: "show", type: "<type>") to see what is required
• Stale pages — review and update content, set last_updated to today, and raise confidence to reflect current certainty; a page with confidence: 0.9 is not stale even if old
• Unknown type — correct the typo in the type: field, or register the new type with wiki_schema(action: "add"); run wiki_schema(action: "list") to see registered types
• Schema issues — fix the schema file, then wiki_schema(action: "validate")
• Edge type mismatches — fix the frontmatter field, then wiki_ingest
• Missing stubs — wiki_content_new(uri: "<slug>", type: "<type>")
• Empty sections — create or move pages under the section

After each fix:

wiki_content_write(uri: "<slug>", content: "<fixed content>")
wiki_ingest(path: "<path>")

Running lint before a review session

wiki_lint findings feed directly into the review skill's priority queue. Run lint immediately before a review session to ensure the queue reflects the current state of the index.