DavidROliverBA/.claude/skills/broken-links

/broken-links

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

Usage

/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)

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)

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)

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:

1. Merge Results

   • Combine all broken links from 3 agents
   • Remove duplicates
   • Group by target note (show all sources linking to same missing note)

2. 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)

3. 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

# 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:

1. Case Mismatch Fixes (automatic)

   • Find: [[project - Cloud Migration]]
   • Should be: [[Project - Cloud Migration]]
   • Auto-fix these with Edit tool

2. Fuzzy Match Replacements (prompt user)

   • Show: "Replace [[Mising Note]] with [[Missing Note]]?"
   • If yes, use Edit tool to fix all occurrences

3. 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.)