/broken-links

Scan the vault for broken [[wiki-links]] and suggest fixes using parallel Sonnet sub-agents.

Usage

code

/broken-links
/broken-links --auto-fix    # Interactive fixes with suggestions

Instructions

This skill uses 3 parallel Sonnet sub-agents to scan different vault areas concurrently for maximum performance.

Phase 1: Launch Parallel Link Scanners

Create 3 Task agents running in parallel with model: "sonnet":

Agent 1: Root Directory Scanner (Sonnet)

code

Task: Scan root directory for broken wiki-links
- Use Glob to find all *.md files in root (exclude +Daily, +Meetings, +Templates)
- For each file, use Read tool to get content
- Extract all [[wiki-links]] using regex: \[\[([^\]|]+)(\|[^\]]+)?\]\]
- Also check frontmatter fields for wiki-links
- Build list of all referenced note names
- Compare against existing files using Glob
- Return: List of broken links with source files
Format:
{
  "source": "filename.md",
  "brokenLinks": ["Missing Note 1", "Missing Note 2"],
  "line": "content snippet with [[broken link]]"
}

Agent 2: Meetings Directory Scanner (Sonnet)

code

Task: Scan +Meetings/ directory for broken wiki-links
- Use Glob to find all *.md files in +Meetings/
- For each file, extract [[wiki-links]] from content and frontmatter
- Check attendees, project links, and inline person references
- Identify missing Person, Project, and Organisation notes
- Return: List of broken links in meeting notes

Agent 3: Daily Notes Scanner (Sonnet)

code

Task: Scan +Daily/ directory for broken wiki-links
- Use Glob to find all *.md files in +Daily/
- Extract [[wiki-links]] from daily notes
- Check task references, project links, person mentions
- Identify temporal references that may be broken
- Return: List of broken links in daily notes

Phase 2: Consolidate Results

After all 3 agents complete:

•
Merge Results
- •Combine all broken links from 3 agents
- •Remove duplicates
- •Group by target note (show all sources linking to same missing note)
•
Categorize by Severity
- •Critical: Links in ADRs, Projects, important Pages (5+ backlinks)
- •Warning: Links in Tasks, Meetings (2-4 backlinks)
- •Info: Links in Daily Notes, single mentions (1 backlink)
•
Fuzzy Match Suggestions
- •
  For each broken link, find similar existing notes:
  - •Case-insensitive matching
  - •Levenshtein distance < 3
  - •Partial word matches
- •Suggest: "Did you mean [[Actual Note]]?"

Phase 3: Generate Report

markdown

# Broken Wiki-Links Report

Generated: {{DATE}}
Total Broken Links: {{count}}

## Critical ({{critical_count}})

### [[Missing Note Name]] (referenced {{count}} times)

**Referenced in:**
- [[Source Note 1]] (line 42): "Context snippet with [[Missing Note Name]]"
- [[Source Note 2]] (line 15): "Another context [[Missing Note Name]]"

**Suggestions:**
- Did you mean [[Similar Note]]? (85% match)
- Did you mean [[Another Match]]? (72% match)

**Actions:**
- [ ] Create the note [[Missing Note Name]]
- [ ] Replace with [[Similar Note]] in all references
- [ ] Remove the broken links

---

## Warnings ({{warning_count}})

{{same format}}

## Info ({{info_count}})

{{same format}}

## Summary

| Severity | Count | % of Total |
|----------|-------|------------|
| Critical | {{n}}  | {{%}}     |
| Warning  | {{n}}  | {{%}}     |
| Info     | {{n}}  | {{%}}     |

## Next Steps

1. **Create Missing Critical Notes**: {{list top 5}}
2. **Fix Case Mismatches**: {{list}}
3. **Review and Clean Up Info-level**: {{list}}

Phase 4: Interactive Fixes (Optional)

If --auto-fix flag is provided:

•
Case Mismatch Fixes (automatic)
- •Find: [[project - Cloud Migration]]
- •Should be: [[Project - Cloud Migration]]
- •Auto-fix these with Edit tool
•
Fuzzy Match Replacements (prompt user)
- •Show: "Replace [[Mising Note]] with [[Missing Note]]?"
- •If yes, use Edit tool to fix all occurrences
•
Bulk Deletions (prompt user)
- •Show: "Remove all references to [[Deleted Note]] (confirmed deleted)?"
- •If yes, remove links but keep context text

Use Cases

Vault Cleanup:

•After bulk file operations (renames, deletions)
•After importing from other tools
•Regular maintenance (monthly checks)

Link Hygiene:

•Fix case mismatches
•Remove links to deleted notes
•Identify orphaned concepts

Refactoring Support:

•Pre-rename validation
•Post-migration verification
•Merge duplicate notes

Quality Assurance:

•Pre-commit validation
•CI/CD pipeline checks
•Vault health monitoring

Performance

•3 parallel agents = 3x faster than sequential scan
•~500 notes: 15-30 seconds
•~2000 notes: 1-2 minutes
•~5000 notes: 3-5 minutes

Notes

•Excludes checking links in +Templates/ (templates often reference non-existent placeholders)
•Handles both [[Note Name]] and [[Note Name|Display Text]] formats
•Checks frontmatter wiki-links (project, attendees, relatedTo, etc.)
•Ignores heading/block references: [[Note#Heading]] → checks Note exists
•Case-sensitive by default, but suggests case mismatches
•Works with all note types (Task, Project, Person, ADR, Meeting, Page, etc.)