wiki-lint

name: wiki-lint description: Runs a structural and content health check on an Obsidian-based LLM knowledge wiki. Detects frontmatter issues, broken or asymmetric cross-references, contradictions, stale claims, tag discipline violations, migration backlog overflow, missing hub pages, and orphan content. Produces a structured lint report. Triggers when the user runs /wiki:lint, asks for a "wiki health check", or asks to lint the knowledge wiki.

When to invoke

The user runs /wiki:lint (typically weekly) or asks for a wiki health check.

Configuration

Same vault layout as wiki-ingest. The migration backlog soft cap (default: 50 files) is configurable via the vault's CLAUDE.md as wiki_migration_cap: <n>.

Workflow

Read all files in <wiki-root>/_wiki/ and <wiki-root>/_raw/. Run the following checks and collect issues.

Deterministic Checks (shared validator)

Run the shared validator over the whole wiki and parse its JSON findings:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/validate.py" \
  --vault-root "<wiki-root>" --rules frontmatter,kindtype,deadlinks,asymmetric

If the validator exits with code 2 (PyYAML missing), fall back to applying the deterministic rules manually from ${CLAUDE_PLUGIN_ROOT}/skills/_shared/validation-rules.md.

Map findings into the report: critical findings go under Critical Issues (Structural for frontmatter/kindtype, Linking for deadlinks/asymmetric); minor findings go under Minor Issues. All rule definitions live in _shared/validation-rules.md — do not restate them here.

(Note: if ${CLAUDE_PLUGIN_ROOT} is unavailable in the runtime, resolve the path relative to this skill: ../_shared/scripts/validate.py.)

Semantic Checks (LLM judgement)

Apply semantic rules 5–8 and template-compliance from ${CLAUDE_PLUGIN_ROOT}/skills/_shared/validation-rules.md (stale claims, contradiction detection, hub gaps, source gaps — type: thinking exempt from source gaps). Keep the Tag Discipline checks (singleton tags, status-as-tag) and the Migration Backlog soft-cap check as they are today.

Tag Discipline

Singleton tags: tags that occur in only one file (aggregated across all frontmatter).
Status-as-tag: tags such as #draft, #tbd, #wip (these belong in the status: field).

Migration Backlog

Soft cap check: count .md files in <wiki-root>/ that live outside _raw/ and _wiki/ (templates are inside _wiki/templates/ and therefore already excluded). If the count exceeds the soft cap (default 50): emit a WARNING.

Auto-Fix Mode

Trivial fixes with diff preview for user confirmation:

Derive missing created: from git log: git log --diff-filter=A --follow --format=%aI -1 -- <file>.
Synchronize asymmetric related: fields bidirectionally.
Add domain: <vault-domain> if the field is missing.

Everything else: report only, do not fix.

Output

Write <wiki-root>/_wiki/lint-report-YYYY-MM-DD.md with frontmatter kind: wiki, type: note and the following structure:

# Lint Report YYYY-MM-DD

## Summary

- Files checked: N
- Issues: M (X critical, Y minor)
- Migration Backlog: Z files (cap: 50, status: OK / OVER by N)

## Critical Issues

### Structural
- ...

### Linking
- ...

## Minor Issues

- ...

## Auto-Fix Suggestions

(diff block per suggestion; user confirms)

## Hub Suggestions

- Cluster `<theme>`: 7 pages without hub. Recommended: `_wiki/concepts/<theme>.md` as type: hub.

Append a log entry:

## [YYYY-MM-DD HH:MM] lint | <report-name>
- issues: M (X critical, Y minor)
- migration backlog: Z files (cap: 50)

Run the markdown-syntax-formatter agent (from the education plugin) on the report. If the education plugin is not installed, skip this step.