Fix Broken Links

Preview broken wikilinks and spawn autonomous repair agent.

When to Use

Invoke when you want to:

• Find all broken wikilinks in vault
• Preview what's broken and why
• Repair broken links automatically
• Improve vault link health

Process

1. Find Broken Links

Call

mcp__flywheel__find_broken_links

to retrieve all broken wikilinks.

2. Analyze Break Patterns

Categorize broken links by type:

Missing Notes (create candidates):

• [[New Topic]]

  → No file exists
• High confidence if referenced multiple times
• Suggest creating note

Typos (fuzzy match):

• [[Databrics]]

  → Did you mean

  [[Databricks]]

  ?
• Use Levenshtein distance
• Auto-fix if confidence >90%

Case Mismatches (exact match different case):

• [[databricks]]

  → Exists as

  [[Databricks]]

• Auto-fix (safe)

Moved Notes (search by title):

• [[Old Path/Note]]

  → Now at

  [[New Path/Note]]

• Search vault for matching title
• Suggest update

3. Show Preview

Display first 20 broken links with categorization:

Broken Links Analysis
═══════════════════════════════════════════════
Found 200 broken links across 50 notes

📊 Breakdown by Type:
  • Missing Notes: 80 (40%)
  • Typos: 40 (20%)
  • Case Mismatches: 30 (15%)
  • Moved/Renamed: 50 (25%)

🔍 Sample (showing 20 of 200):

Missing Notes:
1. [[API Guide]] (15 references)
   → Mentioned in: Projects, Tech Docs
   → Suggestion: Create tech/guides/API.md

Typos:
2. [[Databrics]] → [[Databricks]] (confidence: 95%)
   → Auto-fixable

Case Mismatches:
3. [[azure]] → [[Azure]] (exact match)
   → Auto-fixable

═══════════════════════════════════════════════

💡 Recommendations:
  • Auto-fix: 50 links (high confidence >90%)
  • User review: 60 links (medium confidence 50-90%)
  • Manual fix: 90 links (low confidence <50%)

🤖 Spawn autonomous repair agent?
  • Will process all 200 broken links
  • Auto-fix high confidence (>90%)
  • Present choices for medium confidence (50-90%)
  • Skip low confidence (<50%)

Type 'yes' to spawn link-repair agent

4. User Decision

Ask user if they want to:

• Option A: Spawn agent for autonomous fixing
• Option B: See full list (export to note)
• Option C: Fix specific folder only
• Option D: Cancel (just wanted to see the damage)

Confidence Scoring

Typo Detection (Levenshtein Distance):
- Distance 1: 98% confidence
- Distance 2: 85% confidence
- Distance 3+: <70% confidence

Case Mismatch:
- Exact title match: 100% confidence
- Always safe to auto-fix

Missing Note Analysis:
- Referenced 20+ times: High priority (suggest create)
- Referenced 5-19 times: Medium priority
- Referenced 1-4 times: Low priority (might be scratch)

Moved Note Detection:
- Title exact match: 95% confidence
- Title fuzzy match: 60-85% confidence
- Search by content similarity: <60% confidence

Output Format

Always use the branded format:

Broken Links Analysis
═══════════════════════════════════════════════

[Analysis content]

═══════════════════════════════════════════════

Six Gates Compliance

Gate	Implementation
1. Read Before Write	Finds all broken links via MCP before any fixes
2. File Exists	Validates target notes exist for link suggestions
3. Chain Validation	Agent verifies each fix before proceeding
4. Mutation Confirmation	Shows preview, requires explicit "yes" to proceed
5. Health Check	Uses MCP find_broken_links for vault access
6. Post Validation	Agent reports what was fixed after completion

Safety

• Non-destructive: Only suggests, doesn't auto-apply
• User approval: Requires explicit "yes" to spawn agent
• Preview first: Always show what's broken before fixing
• Backup: Agent will backup before batch edits

Performance

• Discovery: 5-10 seconds (find_broken_links MCP call)
• Analysis: 10-20 seconds (categorize links)
• Preview: Instant (show first 20)
• Total: ~30 seconds before agent spawn decision