sb-lint

name	sb-lint
description	Lint the LLM Wiki for health issues. Use when asked to "lint", "health check", "validate wiki", "check links", "find broken links", "clean up wiki". Reports issues and fixes them after user approval.

LLM Wiki Lint

Run comprehensive health checks on the wiki and optionally fix issues.

Prerequisites

1. Read AGENTS.md to understand conventions
2. Wiki should have pages in wiki/ directory

Step 1: Run Lint Script

Execute the lint script in report mode (default):

uv run scripts/lint.py --wiki-root .

Script will check:

Check	Description	Severity
Broken wikilinks	[[slug]] where no file exists	HIGH
Orphan pages	Pages with no inbound links	MEDIUM
Duplicate titles	Files with same kebab slug (case-insensitive)	HIGH
Empty stubs	Pages still showing "No data yet"	MEDIUM
Stale sources	Source summary pages whose raw file was deleted	LOW
Circular links	A links to B and B links to A	LOW
Missing frontmatter	Pages without required YAML frontmatter	MEDIUM

Step 2: Present Report

Show user the full report:

## Wiki Health Report

### Issues Found: N

#### 🔴 HIGH Priority
- [broken-link] [[neural-netowrks]] → file missing (in sources/attention-is-all-you-need.md:23)
- [duplicate] "attention-is-all-you-need.md" exists in sources/ and sources/archive/

#### 🟡 MEDIUM Priority
- [orphan] [[old-notes-2024.md]] has no inbound links
- [stub] [[transformer-architecture.md]] is still an empty stub

#### 🟢 LOW Priority
- [circular] [[neural-networks]] ↔ [[deep-learning]] (mutual links)
- [stale] Source summary for deleted file: [[old-paper.md]]

### Wiki Stats
- Total pages: 47
- Total wikilinks: 312
- Broken links: 1
- Orphan pages: 3
- Empty stubs: 2

---
Ready to fix? (yes/select/cancel)

Step 3: User Chooses Fixes

User can:

• yes — fix all issues
• select — choose specific issues to fix
• cancel — no fixes

If select:

• Present numbered list of issues
• User specifies which numbers to fix
• Only fix those selected

Step 4: Run Fixes

If user approves fixes:

uv run scripts/lint.py --wiki-root . --fix [--fix-types broken,orphan,stub]

Fix Actions by Type

Issue Type	Fix Action
Broken wikilinks	Create stub page OR remove link (ask user preference)
Orphan pages	Add link from nearest related page OR delete if truly unused
Duplicate titles	Rename one file, update all references
Empty stubs	Ask user to provide content OR delete
Stale sources	Delete source summary page
Circular links	Leave as-is (often intentional)
Missing frontmatter	Add default frontmatter

IMPORTANT: Deterministic Fixes

• Always use scripts to fix, never manually edit
• Back up before fixes: script creates backup in wiki/backups/
• Update all references: if renaming, update all links across wiki
• Log all changes: append to wiki/log.md

Step 5: Verify and Report

After fixes:

## Fixes Applied: N

- ✅ Created stub: [[neural-netowrks]] (was broken link in [[attention-is-all-you-need]])
- ✅ Added frontmatter to: [[some-page.md]]
- ⚠️  Skipped: orphan page [[old-notes.md]] (user chose to keep)

### Backup Location
All original files saved to: wiki/backups/[timestamp]/

Wikilink Validation (Strict Mode)

If wiki is in strict mode (has existing pages):

• Broken links are errors, not warnings
• User must fix before continuing
• No new pages can be created with broken outbound links

Exit Criteria

• Report presented to user
• If fixes approved: all selected issues resolved
• wiki/log.md updated with lint action and results
• Backup created for any deleted/renamed files

Cron/Scheduled Lint

For automated linting, run:

uv run scripts/lint.py --wiki-root . --fix --fix-types broken,stub

This auto-fixes only benign issues (stubs, minor broken links).