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

| Parameter | Typ | Erforderlich | Beschreibung | |-----------|-----|--------------|-------------| | project_path | string | Ja | Absoluter Pfad zum Projektstamm | | check_external | boolean | Nein | Externe URLs verifizieren (Standard: true, langsam) | | fix_mode | enum | Nein | auto (offensichtliche beheben), report (nur dokumentieren), interactive (nachfragen) | | orphan_threshold | integer | Nein | Tage seit letzter Aenderung um als verwaist zu markieren (Standard: 180) |

Vorgehensweise

Schritt 1: Defekte interne Links scannen

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

# Alle Markdown-Dateien finden
find . -name "*.md" -type f > markdown_files.txt

# Alle Markdown-Links extrahieren: [Text](Pfad)
grep -oP '\[.*?\]\(\K[^)]+' *.md | sort | uniq > all_links.txt

# Fuer jeden Link:
while read link; do
  # Externe URLs ueberspringen (http/https)
  if [[ "$link" =~ ^https?:// ]]; then
    continue
  fi

  # Relativen Pfad aufloesen
  target=$(realpath -m "$link")

  # Pruefen ob Ziel existiert
  if [ ! -e "$target" ]; then
    echo "DEFEKT: $link (referenziert 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).

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

# Jede URL pruefen (Ratelimit um Sperren zu vermeiden)
while read url; do
  status=$(curl -o /dev/null -s -w "%{http_code}" "$url")

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

  sleep 0.5  # Ratelimit
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:

# Alle Import-Anweisungen finden
grep -rh "^import.*from ['\"]" . | sed -E "s/.*from ['\"]([^'\"]+)['\"].*/\1/" > imports.txt

# Fuer jeden Import:
while read import; do
  # node_modules und externe Pakete ueberspringen
  if [[ "$import" =~ ^[./] ]]; then
    # Zu Dateipfad aufloesen
    target="${import}.js"  # .js, .ts, .jsx, .tsx versuchen

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

Python:

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

# Fuer jeden lokalen Import (beginnt mit .)
# Pruefen ob Moduldatei existiert

R:

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

# Fuer source()-Aufrufe pruefen ob Datei existiert
# Fuer library()-Aufrufe pruefen ob Paket installiert
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.

# Alle Codedateien finden
find . -type f \( -name "*.js" -o -name "*.py" -o -name "*.R" \) > all_files.txt

# Fuer jede Datei:
while read file; do
  basename=$(basename "$file")

  # Nach Referenzen suchen (Import, Require, Source, href, Link)
  refs=$(grep -r "$basename" . --exclude-dir=node_modules --exclude-dir=.git | wc -l)

  # Wenn nur 1 Referenz (sich selbst):
  if [ "$refs" -le 1 ]; then
    # Letztes Aenderungsdatum pruefen
    last_mod=$(git log -1 --format="%ci" "$file")

    # Wenn laenger als orphan_threshold Tage nicht geaendert
    # Als potenziell verwaist markieren
    echo "VERWAIST: $file (letzte Aenderung: $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

# Fuer jeden defekten Link nach Datei nach Name suchen
while read broken_link; do
  filename=$(basename "$broken_link")

  # Im Projekt nach Datei suchen
  found=$(find . -name "$filename" | head -1)

  if [ -n "$found" ]; then
    # Link auf neuen Pfad aktualisieren
    old_path="$broken_link"
    new_path="$found"

    # Edit-Tool zum Ersetzen in allen Markdown-Dateien verwenden
    echo "KORREKTUR: $old_path -> $new_path"
  fi
done < broken_internal.txt

Strategie 2: Weiterleitungs-Stub erstellen

# Wenn Datei absichtlich geloescht wurde, Weiterleitungs-Stub erstellen
echo "# Verschoben" > "$broken_link"
echo "Dieser Inhalt wurde nach [neuer Ort](new_path.md) verschoben" >> "$broken_link"

Strategie 3: Toten Link entfernen

# Wenn Inhalt nicht mehr existiert, Link entfernen (Text beibehalten)
# [Text](defekter_link) durch Text (Klartext) ersetzen

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:

// Vorher (defekt)
import { helper } from './utils/helper';

// Nachher (repariert — Datei nach lib/ verschoben)
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.

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