Lint Wiki

Lint Knowledge Base Wiki

This skill performs the critical self-healing step for the LLM wiki, preventing errors from compounding over time and ensuring the wiki graph remains clean and well-structured.

Instructions

When the user asks you to run a health check, lint the wiki, or clean up:

0. Resolve Paths (always do this first): First, check if a wiki-config.md exists in the current workspace root (this indicates a project-local wiki). If not found, read wiki-config.md from the same directory as this skill (e.g., ~/.cursor/skills/wiki-config.md) for the global wiki. The file contains four absolute paths labelled Wiki root, Wiki folder, Raw folder, and Output folder. Use these paths everywhere below instead of the relative wiki/, raw/, and output/ defaults. If neither file exists, fall back to relative paths from the workspace root.

1. Run the Structural Pre-Scan: Execute node lint_graph.js with the shell working directory set to Wiki root (the path labelled Wiki root in wiki-config — the directory that contains lint_graph.js and a wiki/ subfolder). This zero-dependency script programmatically checks dangling [[wiki-links]], orphan pages, frontmatter validity (title:/type:/authors:/tags:/date_added:), index sync, and possible duplicate page names. Use its output to focus your manual review on the flagged issues rather than reading every file from scratch.

2. Review the Flagged Pages: For issues flagged by the script (and for checks the script cannot do, like contradictions and claim verification), read the relevant .md files across wiki/ and its thematic subfolders. Exclude index.md and log.md from topic checks.

3. Semantic Health Checks (requires reading content): These checks go beyond what the script can detect and require reading page content:

   • Flag Contradictions: Identify any contradictions between articles. Compare conflicting statements and note them clearly, or synthesize if there's consensus.
   • Verify Claims: Spot any major claims that don't seem to be backed by a source in the raw/ folder. Flag these as needing citation.
   • Suggest New Articles: Based on the gaps in the current knowledge graph, suggest 3 new articles/topics that would fill missing links.

4. Fix Frontmatter Issues: For any pages flagged by the script, ensure valid YAML frontmatter containing:

   • title: — required; the original source title (or wiki page title for concept pages).
   • type: — required; must be one of paper, preprint, article, blog-post, github-repo, book, video, documentation, concept.
   • authors: — required; plain text, never wrapped in [[ ]].
   • tags: — required; at least one tag in lowercase-dash format.
   • date_added: — required; ISO 8601 date YYYY-MM-DD (when the entry was added to the wiki).
   • url: (manual check): If a page has a ## Sources section with exactly one bullet and the page is clearly sourced from that item (not a pure synthesis of many ideas), it should usually have a url: in frontmatter matching the primary link — flag missing url: for human review.

5. Subfolder Hygiene: Flag any topic .md files sitting directly in the wiki/ root that should be organized into a thematic subfolder.

6. Unprocessed Files Check: Cross-reference the files in raw/ against wiki/log.md to catch any raw files that compile-wiki may have missed. Report them so the user can run compile-wiki to process them.

7. Graph Maintenance (Obsidian Integrity): Use the script output as the starting point, then:

   • Merge Redundancies: If the script flagged possible duplicates, or you find two files covering the same topic (e.g., "Evaluating LLMs" and "LLM Evaluation"), merge them into one, delete the duplicate, and update all links to point to the new file.
   • Rescue Orphans: For pages flagged as orphans, add [[wiki-links]] to integrate them into the graph.
   • Fix Unexplained Topics: For dangling links, create brief stub pages or fix the links.
   • Flag Tooling/Meta Nodes: Check for [[wiki-links]] that reference this system's own operational tooling or skills (e.g., "compile-wiki", "lint-wiki", "ask-wiki", "AGENTS.md", "schema file"). These are not knowledge topics and should be plain text, not links. Remove the [[ ]] wrapper from any such references.
   • Prune Hub Pollution: Count inbound links (in-degree) for every page. Any page receiving links from more than ~40% of all topic pages is a suspected hub. For each suspected hub, review every page that links to it and ask: "Is this page specifically about the hub topic's mechanism or a direct novel application of it?" If the link is incidental (e.g., a building control paper linking to a generic "LLM Agents" page just because an LLM was used), remove the [[link]] and leave the concept as plain text. Report the before/after in-degree for each pruned hub.
   • Flag Over-Linked Pages: Pages with more than 6 outgoing [[wiki-links]] should be reviewed. For each, keep only the 2–5 most conceptually significant links — those where the target topic is essential to understanding the source page. Demote the rest to plain text. The goal is a graph with clear cluster structure, not a hairball where everything is 1–2 hops from everything else.
   • Index Sync: For any mismatches between wiki/index.md and the actual topic files, add missing entries or remove stale ones.

8. Log the Pass and Save the Report:

   • Append a row to wiki/log.md detailing the timestamp of the health check and a summary of actions taken (e.g., "Linting Pass: Flagged 1 contradiction, merged 2 redundancies, suggested 3 new topics").
   • Save the full lint report as a .md file in the output/ directory (e.g., output/Lint Report - YYYY-MM-DD.md).

9. (Optional) Refresh the OKF export: If the user wants a portable Open Knowledge Format bundle for external tooling, run node export_okf.js from Wiki root (same directory as lint_graph.js). It non-destructively regenerates output/okf/ — rewriting [[wiki-links]] into bundle-relative markdown links and adding OKF resource/timestamp aliases — leaving the native wiki/ untouched. Skip unless asked; the native wiki is the source of truth.

Output

Provide the user with a markdown summary of the health check results, including the 3 suggested new articles, any contradictions/unbacked claims found, frontmatter issues, and unprocessed raw files.