lint

Lint workflow

Prerequisites

• Verify wiki/index.md and wiki/log.md exist. If either is missing, suggest running /ingest on a source first — it will bootstrap the wiki automatically.

1. Read wiki/index.md and scan all wiki pages in wiki/.

   • Scalability note: For wikis with >50 pages, use the AskUserQuestion tool to offer scoped lint instead of scanning everything. Options: "Full wiki lint", "By subdirectory", "By lens", "Recent changes only". Include descriptions explaining the trade-off (thoroughness vs. speed). For full-wiki lints at scale, process one subdirectory at a time and report incrementally.
   • Lens awareness: Read .llm-wiki/lenses/ to load active lens definitions. These are needed for lens-specific quality validation in content checks.

2. Run checks across four categories:

   Structural checks

   • Orphan pages — pages with no inbound [[wikilinks]] from other pages
   • Broken links — [[wikilinks]] pointing to pages that don't exist
   • Index gaps — pages in wiki/ not listed in wiki/index.md, or index entries pointing to missing pages
   • Missing See also — pages lacking the mandatory ## See also section
   • Frontmatter issues — missing or malformed YAML frontmatter, wrong page type
   • Misplaced files — pages in the wrong subdirectory for their type (e.g., a concept page outside wiki/concepts/)
   • Lens consistency — pages with a lens frontmatter field that references a non-existent or archived lens file in .llm-wiki/lenses/
   • Lens-specific type placement — pages with lens-defined custom types that are not in the correct subdirectory as specified by the lens

   Content checks

   • Contradictions — conflicting claims across pages (flag with specific quotes from both pages)
   • Stale content — claims that newer sources have superseded
   • Thin pages — pages missing required sections for their type:
     • concept: definition, principles, implications, relationships, See also
     • technique: what, when, how, example, pitfalls, See also
     • entity: background, key contributions, works, See also
     • For lens-tagged pages: also validate against the lens's "Quality Standards" section (additional required sections/fields)
   • Incomplete pages — pages with content that could be expanded from existing sources

   Cross-reference checks

   • One-directional links — page A links to page B in body, but B has no link back (even in See also)
   • Missing lateral links — concept/technique clusters that should be interlinked but aren't
   • Entity hub gaps — entity pages not linking to all their attributed concepts/techniques

   Growth suggestions

   • Missing pages — important concepts, techniques, or entities mentioned across pages that lack their own page
   • Topics to explore — areas where the wiki has thin coverage relative to its depth elsewhere
   • Potential sources — suggest what kinds of sources could fill identified gaps
   • Cross-lens connections — pages in different lenses that share related concepts but lack cross-references between them

3. Categorize findings by severity:

   • fix — broken, should repair now (broken links, index gaps, missing frontmatter)
   • improve — quality gap, optional but recommended (thin pages, missing See also, one-directional links)
   • explore — growth opportunity (missing pages, topics to explore, potential sources)

4. Report findings. Present a summary organized by severity, then by check category. Be specific — cite exact pages and passages, not vague observations.

5. Offer to fix. Use the AskUserQuestion tool to ask which issues to address. Options: "Fix all issues", "Only fix-severity items (Recommended)", "Let me pick specific items", "No fixes now". Fix in batches by severity (all fix items first, then improve, then explore). When fixing:

   • Add cross-references and See also sections
   • Create missing pages following quality standards
   • Update the index
   • Resolve contradictions (flag which source to trust and why)

6. Update wiki/log.md. Append:

   ## [YYYY-MM-DD] lint | Summary
   
   **Found:** X fix, Y improve, Z explore
   **Fixed:** (list of what was addressed)
   **Deferred:** (list of what was left for later)
   

Guidelines

• Be specific — cite exact pages and passages, not vague observations.
• Prioritize fix issues (broken, affects usability) over improve (quality) over explore (growth).
• Suggest new questions to investigate and new sources to look for based on gaps found.
• After fixing, re-run structural checks (broken links, index gaps, missing See also) on all pages that were created or modified during the fix pass. Report any new issues introduced.