| 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
- Read
AGENTS.md to understand conventions
- 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).
