repair-broken-references

Use When

Use when project refs gone stale:

• Docs has broken internal links
• External URLs return 404
• Imports ref moved/deleted modules
• Cross-refs between files out of sync
• Files exist but never ref'd anywhere

Do NOT use for refactoring module deps or redesigning info arch. This repairs existing refs, not restructures.

In

Parameter	Type	Required	Description
project_path	string	Yes	Absolute path to project root
check_external	boolean	No	Verify external URLs (default: true, slow)
fix_mode	enum	No	auto (fix obvious), report (document only), interactive (prompt)
orphan_threshold	integer	No	Days since last modified to flag as orphan (default: 180)

Do

Step 1: Scan Broken Internal Links

Find all markdown links → non-existent files.

# Find all markdown files
find . -name "*.md" -type f > markdown_files.txt

# Extract all markdown links: [text](path)
grep -oP '\[.*?\]\(\K[^)]+' *.md | sort | uniq > all_links.txt

# For each link:
while read link; do
  # Skip external URLs (http/https)
  if [[ "$link" =~ ^https?:// ]]; then
    continue
  fi

  # Resolve relative path
  target=$(realpath -m "$link")

  # Check if target exists
  if [ ! -e "$target" ]; then
    echo "BROKEN: $link (referenced in $file)" >> broken_internal.txt
  fi
done < all_links.txt

→ broken_internal.txt lists all broken internal refs

If err: realpath unavailable → manual check each link

Step 2: Check External URLs

Verify external links accessible (HTTP 200).

# Extract external URLs
grep -ohP 'https?://[^\s\)]+' *.md | sort | uniq > external_urls.txt

# Check each URL (rate-limit to avoid bans)
while read url; do
  status=$(curl -o /dev/null -s -w "%{http_code}" "$url")

  if [ "$status" -ge 400 ]; then
    echo "DEAD ($status): $url" >> dead_urls.txt
  fi

  sleep 0.5  # Rate limit
done < external_urls.txt

→ dead_urls.txt lists URLs returning 4xx/5xx

If err: curl unavail or blocked → use online link checker or skip

Note: Some URLs return 403 due to bot detection but work in browsers. Manual review needed.

Step 3: Find Broken Imports

Check all import/require → existing modules.

JavaScript/TypeScript:

# Find all import statements
grep -rh "^import.*from ['\"]" . | sed -E "s/.*from ['\"]([^'\"]+)['\"].*/\1/" > imports.txt

# For each import:
while read import; do
  # Skip node_modules and external packages
  if [[ "$import" =~ ^[./] ]]; then
    # Resolve to file path
    target="${import}.js"  # Try .js, .ts, .jsx, .tsx

    if [ ! -e "$target" ]; then
      echo "BROKEN IMPORT: $import" >> broken_imports.txt
    fi
  fi
done < imports.txt

Python:

# Find all import statements
grep -rh "^from .* import\|^import " . --include="*.py" | \
  sed -E "s/from ([^ ]+) import.*/\1/" | \
  sed -E "s/import ([^ ]+)/\1/" > imports.txt

# For each local import (starts with .)
# Check if module file exists

R:

# Find library() and source() calls
grep -rh "library(\\|source(" . --include="*.R" | \
  sed -E 's/.*library\("([^"]+)"\).*/\1/' > packages.txt

# For source() calls, check if file exists
# For library() calls, check if package installed
Rscript -e "installed.packages()[,'Package']" > installed_packages.txt

→ broken_imports.txt lists all refs to deleted/moved modules

If err: lang-specific tool unavail → manual review recent refactor commits

Step 4: Find Orphaned Files

ID files exist but never ref'd.

# Find all code files
find . -type f \( -name "*.js" -o -name "*.py" -o -name "*.R" \) > all_files.txt

# For each file:
while read file; do
  basename=$(basename "$file")

  # Search for references (import, require, source, href, link)
  refs=$(grep -r "$basename" . --exclude-dir=node_modules --exclude-dir=.git | wc -l)

  # If only 1 reference (itself):
  if [ "$refs" -le 1 ]; then
    # Check last modified date
    last_mod=$(git log -1 --format="%ci" "$file")

    # If modified more than orphan_threshold days ago
    # Flag as potential orphan
    echo "ORPHAN: $file (last modified: $last_mod)" >> orphans.txt
  fi
done < all_files.txt

→ orphans.txt lists files not ref'd elsewhere

If err: git log fails → use filesystem mtime

Note: Some files (CLI entry points, top-level scripts) legitimately unref'd but not orphans. Manual review.

Step 5: Fix Internal Links

Repair broken refs via 3 strategies:

Strategy 1: Find Moved Files

# For each broken link, search for file by name
while read broken_link; do
  filename=$(basename "$broken_link")

  # Search for file in project
  found=$(find . -name "$filename" | head -1)

  if [ -n "$found" ]; then
    # Update link to new path
    old_path="$broken_link"
    new_path="$found"

    # Use Edit tool to replace in all markdown files
    echo "FIX: $old_path -> $new_path"
  fi
done < broken_internal.txt

Strategy 2: Create Redirect Stub

# If file was deleted intentionally, create redirect stub
echo "# Moved" > "$broken_link"
echo "This content moved to [new location](new_path.md)" >> "$broken_link"

Strategy 3: Remove Dead Link

# If content no longer exists, remove link (keep text)
# Replace [text](broken_link) with text (plain)

→ All broken internal links fixed, redirected, or removed

If err: auto fix breaks ctx → escalate manual review

Step 6: Fix Broken Imports

Update import statements → correct paths after moves.

JavaScript Example:

// Before (broken)
import { helper } from './utils/helper';

// After (fixed — file moved to lib/)
import { helper } from './lib/helper';

For each broken import:

1. Locate moved module (similar Step 5)
2. Update import path in all files ref'ing
3. Run linter/type checker → verify fix

→ All imports resolve correctly; no module-not-found errs

If err: module truly deleted → escalate to determine if functionality still needed

Step 7: Document Orphans

For files flagged orphans, determine disposition:

1. Keep: Legitimately unref'd (entry points, scripts, templates)
2. Archive: Old code no longer needed, preserve history
3. Delete: Dead code, no value

# Orphaned Files Review

| File | Last Modified | Recommendation | Reason |
|------|---------------|----------------|--------|
| scripts/old_deploy.sh | 2024-01-05 | Archive | Replaced by CI/CD |
| src/legacy_api.js | 2023-06-12 | Delete | API v1 fully deprecated |
| bin/cli.py | 2025-12-01 | Keep | CLI entry point (unreferenced by design) |

→ Orphan review doc created; auto decisions flagged for human approval

If err: (N/A — document even if no clear disposition)

Step 8: Generate Report

Summarize all broken refs + fixes.

# Reference Repair Report

**Date**: YYYY-MM-DD
**Project**: <project_name>
**Fix Mode**: auto | report | interactive

## Broken Internal Links

- Total: X
- Fixed: Y
- Redirected: Z
- Escalated: W

Details:
- [file.md](file.md) line 45: Fixed broken link to moved doc
- [another.md](another.md) line 12: Created redirect stub

## Dead External URLs

- Total: X
- Fixed (wayback machine): Y
- Removed: Z

Details:
- https://example.com/old-page (404) → Removed
- https://api.old.com/docs (gone) → Replaced with new docs

## Broken Imports

- Total: X
- Fixed: Y
- Escalated: Z

Details:
- src/main.js line 3: Updated import path after refactor

## Orphaned Files

- Total: X
- Kept: Y
- Archived: Z
- Escalated for review: W

See ORPHAN_REVIEW.md for full analysis.

## Validation

- [x] All tests pass after fixes
- [x] Linter reports no module-not-found errors
- [x] Dead links documented in report

→ Report saved → REFERENCE_REPAIR_REPORT.md

If err: (N/A — generate report regardless)

Check

After repairs:

• No broken internal links in docs
• Dead external URLs documented (not all fixable)
• All imports resolve correctly
• Orphans reviewed + dispositioned
• Tests pass after import fixes
• Linter no unresolved refs
• Git history preserved (used git mv for moves)

Traps

1. Auto URL Fixes Break Ctx: Replacing dead links w/ web.archive.org may not be what author intended. Some better removed.

2. Over-Aggressive Orphan Delete: Entry points, CLI scripts, templates often unref'd by design. Don't delete w/o review.

3. Import Path Assumptions: Assuming all relative imports use same base path. Diff module systems (CommonJS, ES6, TS) handle paths diff.

4. External URL False Positives: Some sites block curl/bots but work browsers. Always manually verify dead URLs.

5. Circular Ref Traps: File A imports B, B imports A. Updating one breaks other. Needs simul fix.

6. Ignoring Fragment IDs: Fixing [link](#section) needs check if #section anchor exists, not just if file exists.

7. Wrong R binary on hybrid systems: WSL or Docker → Rscript may resolve to cross-platform wrapper not native R. Check which Rscript && Rscript --version. Prefer native R binary (e.g. /usr/local/bin/Rscript on Linux/WSL). See Setting Up Your Environment for R path config.

→

• clean-codebase — remove dead code after confirming orphans
• tidy-project-structure — reorganize files (may create broken refs)
• escalate-issues — route complex ref issues to specialists
• compliance/documentation-audit — comprehensive docs review
• web-dev/link-checker — advanced external URL validation