---

name: repair-broken-references locale: de source_locale: en source_commit: 75ded7a1 fence_basis_commit: 75ded7a1 translator: claude translation_date: "2026-03-17" description: > Defekte interne Links, tote externe URLs, veraltete Imports, fehlende Querverweise und verwaiste Dateien finden und reparieren. Stellt sicher dass alle Projektreferenzen gueltig und aktuell bleiben. Anwenden wenn Dokumentation defekte interne Links enthaelt, externe URLs 404-Fehler zurueckgeben, Import-Anweisungen auf verschobene oder geloeschte Module verweisen, Querverweise zwischen Dateien nicht synchron sind oder Dateien existieren die nirgends im Projekt referenziert werden. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: maintenance complexity: intermediate language: multi tags: maintenance, links, imports, references, orphans

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.

# 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