Repair Broken References

Defekte Referenzen reparieren

Wann verwenden

Diesen Skill verwenden wenn Projektreferenzen veraltet sind:

• Dokumentation enthaelt defekte interne Links
• Externe URLs geben 404-Fehler zurueck
• Import-Anweisungen verweisen auf verschobene oder geloeschte Module
• Querverweise zwischen Dateien sind nicht synchron
• Dateien existieren die nirgends referenziert werden

NICHT verwenden fuer Refactoring von Modulabhaengigkeiten oder Neugestaltung der Informationsarchitektur. Dieser Skill repariert bestehende Referenzen, strukturiert sie nicht um.

Eingaben

Vorgehensweise

Schritt 1: Defekte interne Links scannen

Alle Markdown-Links finden die auf nicht existierende Dateien zeigen.

# 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

Erwartet: broken_internal.txt listet alle defekten internen Referenzen auf

Bei Fehler: Wenn realpath nicht verfuegbar, jeden Link manuell pruefen

Schritt 2: Externe URLs pruefen

Verifizieren dass externe Links noch erreichbar sind (HTTP 200 Antwort).

# 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

Erwartet: dead_urls.txt listet URLs die 4xx/5xx-Fehler zurueckgeben

Bei Fehler: Wenn curl nicht verfuegbar oder blockiert, Online-Link-Checker verwenden oder ueberspringen

Hinweis: Einige URLs koennen 403 zurueckgeben wegen Bot-Erkennung, funktionieren aber im Browser. Manuelle Pruefung erforderlich.

Schritt 3: Defekte Imports finden

Pruefen dass alle Import-/Require-Anweisungen auf existierende Module verweisen.

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

Erwartet: broken_imports.txt listet alle Referenzen auf geloeschte/verschobene Module

Bei Fehler: Wenn sprachspezifisches Werkzeug nicht verfuegbar, kuerzliche Refactoring-Commits manuell pruefen

Schritt 4: Verwaiste Dateien finden

Dateien identifizieren die existieren aber nirgends referenziert werden.

# 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

Erwartet: orphans.txt listet Dateien die anderweitig nicht referenziert werden

Bei Fehler: Wenn git log fehlschlaegt, stattdessen Dateisystem-mtime verwenden

Hinweis: Einige Dateien (z.B. CLI-Einstiegspunkte, Top-Level-Skripte) sind legitimerweise unreferenziert aber keine Waisen. Erfordert manuelle Pruefung.

Schritt 5: Interne Links reparieren

Defekte interne Referenzen mit einer von drei Strategien reparieren:

Strategie 1: Verschobene Dateien finden

# 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

Strategie 2: Weiterleitungs-Stub erstellen

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

Strategie 3: Toten Link entfernen

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

Erwartet: Alle defekten internen Links entweder repariert, weitergeleitet oder entfernt

Bei Fehler: Wenn automatische Korrektur den Kontext bricht, zur manuellen Pruefung eskalieren

Schritt 6: Defekte Imports reparieren

Import-Anweisungen aktualisieren um nach Verschiebungen auf korrekte Pfade zu verweisen.

JavaScript-Beispiel:

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

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

Fuer jeden defekten Import:

1. Verschobenes Modul finden (aehnlich wie Schritt 5)
2. Importpfad in allen referenzierenden Dateien aktualisieren
3. Linter/Typechecker zur Verifizierung der Korrektur ausfuehren

Erwartet: Alle Imports loesen korrekt auf; keine Modul-nicht-gefunden-Fehler

Bei Fehler: Wenn Modul tatsaechlich geloescht wurde, eskalieren um festzustellen ob Funktionalitaet noch benoetigt wird

Schritt 7: Verwaiste Dateien dokumentieren

Fuer als verwaist markierte Dateien Verwendungszweck bestimmen:

1. Behalten: Legitimerweise unreferenziert (Einstiegspunkte, Skripte, Vorlagen)
2. Archivieren: Alter Code nicht mehr benoetigt aber Historie bewahren
3. Loeschen: Toter Code ohne Wert

# Pruefung verwaister Dateien

| Datei | Letzte Aenderung | Empfehlung | Grund |
|-------|------------------|------------|-------|
| scripts/old_deploy.sh | 2024-01-05 | Archivieren | Durch CI/CD ersetzt |
| src/legacy_api.js | 2023-06-12 | Loeschen | API v1 vollstaendig abgekuendigt |
| bin/cli.py | 2025-12-01 | Behalten | CLI-Einstiegspunkt (absichtlich unreferenziert) |

Erwartet: Dokument zur Pruefung verwaister Dateien erstellt; automatische Entscheidungen zur menschlichen Genehmigung markiert

Bei Fehler: (Entfaellt — auch ohne klare Empfehlung dokumentieren)

Schritt 8: Reparaturbericht erstellen

Alle defekten Referenzen und angewandten Korrekturen zusammenfassen.

# Referenz-Reparaturbericht

**Datum**: JJJJ-MM-TT
**Projekt**: <projektname>
**Korrekturmodus**: auto | report | interactive

## Defekte interne Links

- Gesamt: X
- Repariert: Y
- Weitergeleitet: Z
- Eskaliert: W

Details:
- [datei.md](datei.md) Zeile 45: Defekten Link zu verschobenem Dokument repariert
- [andere.md](andere.md) Zeile 12: Weiterleitungs-Stub erstellt

## Tote externe URLs

- Gesamt: X
- Repariert (Wayback Machine): Y
- Entfernt: Z

Details:
- https://example.com/old-page (404) → Entfernt
- https://api.old.com/docs (verschwunden) → Durch neue Dokumentation ersetzt

## Defekte Imports

- Gesamt: X
- Repariert: Y
- Eskaliert: Z

Details:
- src/main.js Zeile 3: Importpfad nach Refactoring aktualisiert

## Verwaiste Dateien

- Gesamt: X
- Behalten: Y
- Archiviert: Z
- Zur Pruefung eskaliert: W

Siehe ORPHAN_REVIEW.md fuer vollstaendige Analyse.

## Validierung

- [x] Alle Tests bestehen nach Korrekturen
- [x] Linter meldet keine Modul-nicht-gefunden-Fehler
- [x] Tote Links im Bericht dokumentiert

Erwartet: Bericht in REFERENCE_REPAIR_REPORT.md gespeichert

Bei Fehler: (Entfaellt — Bericht unabhaengig generieren)

Validierung

Nach Reparaturen:

• Keine defekten internen Links in Dokumentation
• Tote externe URLs dokumentiert (nicht alle reparierbar)
• Alle Imports loesen korrekt auf
• Verwaiste Dateien geprueft und zugeordnet
• Tests bestehen nach Import-Korrekturen
• Linter meldet keine unaufgeloesten Referenzen
• Git-Historie erhalten (verwendet git mv fuer Verschiebungen)

Haeufige Stolperfallen

1. Automatische URL-Korrekturen brechen Kontext: Tote Links durch web.archive.org-URLs zu ersetzen entspricht moeglicherweise nicht der Absicht des Autors. Manche Links werden besser entfernt.

2. Ueberagressive Waisen-Loeschung: Einstiegspunkte, CLI-Skripte und Vorlagen sind oft absichtlich unreferenziert. Nicht ohne Pruefung loeschen.

3. Import-Pfad-Annahmen: Annahme dass alle relativen Imports denselben Basispfad verwenden. Verschiedene Modulsysteme (CommonJS, ES6, TypeScript) behandeln Pfade unterschiedlich.

4. Externe URL Falsch-Positive: Einige Websites blockieren curl/Bots funktionieren aber einwandfrei im Browser. Tote URLs immer manuell verifizieren.

5. Zirkulaere Referenz-Fallen: Datei A importiert B, B importiert A. Aktualisierung einer bricht die andere. Erfordert gleichzeitige Korrektur.

6. Fragment-Bezeichner ignorieren: Reparatur von [Link](#abschnitt) erfordert Pruefung ob der #abschnitt-Anker existiert, nicht nur ob die Datei existiert.

7. Falsches R-Binary auf Hybrid-Systemen: Unter WSL oder Docker kann Rscript einen plattformuebergreifenden Wrapper statt nativem R aufloesen. Mit which Rscript && Rscript --version pruefen. Das native R-Binary bevorzugen (z.B. /usr/local/bin/Rscript unter Linux/WSL) fuer Zuverlaessigkeit. Fuer die R-Pfadkonfiguration siehe Setting Up Your Environment.

Verwandte Skills

• clean-codebase — Toten Code entfernen nach Bestaetigung verwaister Dateien
• tidy-project-structure — Dateien reorganisieren (kann defekte Referenzen erzeugen)
• escalate-issues — Komplexe Referenzprobleme an Spezialisten weiterleiten
• compliance/documentation-audit — Umfassende Dokumentationspruefung
• web-dev/link-checker — Erweiterte externe URL-Validierung