Skip to content

DavidROliverBA/ArchitectKB / .claude/skills/broken-links

broken-links

Verified

FileKindSize
SKILL.mdskill md5.1 KB
---
context: fork
---

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

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

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.)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall