notque/kb-lint

KB Lint Skill

Health check a knowledge base wiki under research/{topic}/ for structural consistency, broken references, and content quality gaps. Produces a structured lint report.

Invocation

/kb-lint --topic TOPIC [--fix]

• --topic TOPIC — the topic slug under research/
• --fix — attempt to auto-fix structural errors (missing index entries, broken links)

Phase 1: INVENTORY

Read research/{topic}/kb.yaml. Count all files:

• raw/ — raw source markdown files
• wiki/concepts/ — concept articles
• wiki/sources/ — source summary articles
• wiki/queries/ — saved query outputs

Read research/{topic}/wiki/_index.md.

Report current state:

KB '{topic}': N raw sources, M concepts, P source summaries, Q queries.
Last compiled: {last_compiled from _index.md frontmatter, or "never"}.

Phase 2: STRUCTURAL CHECKS

Run deterministic checks. Read file contents and frontmatter as needed. Do NOT read raw sources for structural checks — wiki files only.

| Check | Pass Condition | Severity | |-------|----------------|----------| | Raw coverage | Every raw/*.md has a matching wiki/sources/*.md | ERROR | | Concept backlinks | Every concept slug in source frontmatter concepts: list exists as wiki/concepts/{slug}.md | ERROR | | Source backlinks | Every source slug in concept frontmatter sources: list exists as wiki/sources/{slug}.md | WARN | | Index completeness | Every .md file under wiki/ (excluding _index.md) appears in _index.md | ERROR | | Orphan concepts | Concepts that appear in 0 source concepts: lists | WARN | | Empty articles | Wiki files with fewer than 50 words of content (excluding frontmatter block) | WARN | | Stale index | _index.md frontmatter last_compiled is more than 7 days old | WARN | | Missing frontmatter | Any wiki file (concepts, sources, queries) that lacks a valid YAML frontmatter block | ERROR | | Broken cross-links | Markdown links [text](path) within wiki files that point to non-existent files | ERROR |

For each check:

• Collect all failures with specific file names
• Accumulate counts: errors, warnings

Phase 3: CONTENT QUALITY

LLM-judged quality checks on concept articles. Read up to 10 concept articles (or all if fewer than 10). For each:

Article-level checks:

• Is the article just a title with no substance? (fewer than 3 sentences of actual content)
• Does the article have a definition or overview section?
• Does the article contain contradictory statements?

Cross-article checks (after reading the sample):

• Concept overlap: are two concepts covering substantially the same topic? Flag pairs and suggest merging.
• Gap analysis: based on sources referenced and concepts present, are there obvious missing concepts? List up to 5 significant gaps only — do not suggest minor terms.

Phase 4: REPORT

Produce a structured report to stdout. Format:

# KB Lint Report: {topic}

## Summary
- Total: N raw, M concepts, P sources, Q queries
- Errors: X | Warnings: Y | Suggestions: Z

## Errors
- [ERROR] {description with specific file name(s)}

## Warnings
- [WARN] {description with specific file name(s)}

## Suggestions
- [SUGGEST] {description}

## Recommended Actions
1. {specific action to fix most critical issue}
2. {next action}
3. ...

If there are no errors, no warnings, and no suggestions, output:

KB '{topic}' is healthy. No issues found.

Auto-fix behavior (--fix)

If --fix was specified AND structural errors were found, offer to repair:

• Missing index entries: append missing file paths to _index.md articles list
• Broken [[wiki/path]]-style links: report only (cannot safely infer correct target)

Before fixing, print each planned change and ask for confirmation. Do NOT auto-fix content quality issues — those require human or LLM judgment during compile.

Anti-patterns

• Do NOT fix issues silently — always report before fixing
• Do NOT suggest concepts for every minor term — only significant gaps (max 5)
• Do NOT report passing checks — only failures and suggestions
• Do NOT read every raw source during lint — structural checks use wiki files only
• Do NOT treat missing research/{topic}/ as a lint failure — exit with a clear error message before phase 1