lint-vault

name	lint-vault
description	Run health checks on the wiki vault. Finds stubs, orphans, redlinks, inconsistencies, weak links, and missing connections. Use when asked to "lint", "health check", "audit wiki", or "check wiki integrity".

Audit the vault's `wiki/` directory for structural health: count articles by status and type, detect stubs, orphans, redlinks, weak articles, missing bidirectional links, index gaps, and unprocessed raw sources. Produce a structured report and offer targeted fixes.

<quick_start>

1. Locate vault root — use current working directory
2. Read docs/conventions.md for schema rules
3. Scan all wiki/*.md files (excluding _-prefixed index files)
4. Parse frontmatter and wikilinks from every article
5. Cross-reference against index files and raw sources
6. Print health report
7. Offer to fix issues </quick_start>

**Step 1: Scan wiki state**

Collect all wiki articles: wiki/*.md files where filename does NOT start with _. For each article, extract:

• title, type, domains, status from frontmatter
• All outbound [[wikilinks]] found in body and related field

Compute:

• Total article count
• Count by status: stub / draft / evergreen
• Count by type: concept / paper / tool / person / company / technique / framework

Step 2: Find issues

Run each check in sequence:

Stubs needing content Collect all articles where status: stub. These need fleshing out.

Orphan articles Build a set of all article filenames. For each article, collect every [[wikilink]] target mentioned across all articles (body + related). An orphan is any article that appears in zero inbound links from other wiki articles. Index files (_index.md, domain indexes) do not count as inbound links for this check.

Redlinks Collect every [[wikilink]] target across all articles. A redlink is a target that does NOT match any existing wiki article filename or title. These are future article candidates. Track how many articles reference each redlink.

Weak articles An article is weak if it contains fewer than 3 outbound [[wikilinks]] in body + related combined. The convention requires at least 3.

Missing bidirectional links For each pair where Article A links to Article B (either in body or related): check if Article B links back to Article A in its body or related. Collect all missing backlinks.

Index gaps Read wiki/_index.md. Collect all article titles/filenames listed there. Any wiki article not found in _index.md is an index gap.

Domain index gaps For each article, read its domains field. For each domain, check the corresponding domain index file in wiki/. If the article isn't listed there, it's a domain index gap.

Stale sources Scan raw/ recursively for any files where processed: is false or the field is absent entirely. These are unprocessed sources.

Step 3: Suggest improvements

Based on findings:

1. Top redlink candidates — list the 5–10 redlinks referenced by the most articles. These should become articles first.

2. Stubs to prioritize — sort stubs by inbound link count (most-referenced stubs first). These are the highest-leverage to flesh out.

3. Suggested connections — for pairs of articles that share a domains value but have no wikilink between them, suggest adding cross-links. Focus on articles with fewer than 5 outbound links (most likely to benefit).

Step 4: Report

Print this exact structure:

## Wiki Health Report

### Stats
- Total articles: X (Y stubs, Z drafts, W evergreen)
- Types: X concepts, X papers, X tools, X people, X companies, X techniques, X frameworks

### Issues Found
- X stubs needing content
- X orphan articles (no inbound links)
- X redlinks (future article candidates)
- X weak articles (< 3 wikilinks)
- X missing bidirectional links
- X index gaps (not in _index.md)
- X domain index gaps
- X unprocessed raw sources

### Orphan Articles
(list them, one per line)

### Top Redlinks (most referenced, not yet created)
1. [[Article Name]] — referenced by X articles
2. ...

### Weak Articles (< 3 wikilinks)
(list article name + current outbound count)

### Missing Bidirectional Links
(list: "[[A]] links to [[B]] but B doesn't link back")

### Index & Domain Gaps
(list missing entries)

### Suggested Actions
1. Create article for [[Top Redlink]] — referenced by N articles
2. Flesh out stub [[Stub Name]] — linked from N articles
3. Add [[A]] ↔ [[B]] cross-links — both in domain X, no current link

Step 5: Append log entry

Append to wiki/log.md:

## [YYYY-MM-DD] lint | Health check

- Issues found: X stubs, X orphans, X redlinks
- Fixed: (list what was fixed, if anything)

Step 6: Offer to fix

After the report, ask:

"Want me to fix any of these? I can: (a) flesh out stubs — expand stub articles into full drafts (b) add missing links — insert backlinks and bidirectional links (c) update indexes — sync _index.md and domain indexes (d) create articles for top redlinks — draft new articles for most-referenced missing entries (e) all of the above"

Wait for the user's choice before proceeding.

<success_criteria> The lint run is complete when:

• All wiki articles have been scanned (none skipped)
• All 7 issue categories have been checked and counted
• The health report is printed in full
• Redlinks are ranked by reference count
• Stubs are ranked by inbound link count
• The user has been offered fix options and a choice has been acknowledged </success_criteria>