debugging-and-error-recovery

Débogage discipliné par cause racine pour scripts Python, VPS (systemd/Docker/SFTP), pipelines de veille et automatisations maison. À utiliser quand un test échoue, un build casse, un timer ou une tâc

SKILL.md

GitHub

Débogage par cause racine

Objectif : trouver et corriger LA cause, pas un symptôme.

Règles citées, en une ligne chacune (détail dans ${CLAUDE_PLUGIN_ROOT}/references/regles.md) :

  • R22 — au deuxième échec identique, s'arrêter, chercher la cause racine et changer de méthode.
  • R48 — toute erreur rencontrée est consignée en fin de session (symptôme, cause, correctif).
  • R51 — un cache ou une note n'est pas l'état réel : recouper sur la machine avant d'affirmer.

Méthode (séquentielle)

  1. Reproduire de façon fiable et minimale (commande et contexte exacts). Non reproductible → instrumenter d'abord (→ observability-and-instrumentation).
  2. Observer les faits avant toute hypothèse : message complet, stacktrace, logs (journalctl -u <unit>, fichiers *.log), code de sortie, état réel (processus, fichiers, systemctl list-timers, docker ps).
  3. Une hypothèse falsifiable à la fois : « si X, alors je verrais Y » → tester Y.
  4. Bissection : réduire la surface (dry-run, git bisect, isoler le sous-script) jusqu'au point de bascule.
  5. Corriger la cause, pas le symptôme ; vérifier qu'aucune autre branche n'en dépendait.
  6. Prouver : rejouer le cas + un cas voisin (régression).
  7. Capitaliser (R48) : une entrée dans le log d'erreurs du projet (par exemple 40_ERRORS/) — symptôme, cause, correctif, pattern si récurrent.

Exemple — timer systemd muet

Symptôme : « la veille n'a rien produit depuis deux jours ».

  1. systemctl list-timers --all | grep veille → le timer existe, LAST date d'il y a deux jours, NEXT à n/a : il ne se réarme pas.
  2. systemctl status veille.service → inactive (dead), dernier résultat exit-code.
  3. journalctl -u veille.service --since "3 days ago" → ModuleNotFoundError: paramiko à la première ligne de l'exécution ratée ; la veille précédente passait.
  4. Hypothèse : le virtualenv a été recréé sans la dépendance → ls <venv>/lib/*/site-packages | grep paramiko → absent. Confirmé.
  5. Cause : réinstallation du venv la veille sans requirements.txt à jour. Correctif : ajouter la dépendance au fichier, réinstaller, systemctl start veille.service → exit 0 ; list-timers affiche à nouveau un NEXT.
  6. Entrée au log d'erreurs : « timer muet ≠ timer cassé : lire status puis journalctl avant de toucher à l'unité ».

Pièges connus

  • Cache ≠ source (R51). Quoting PowerShell → bash (le $ disparaît) : passer par un fichier de commande.
  • Encodage : un chemin ou une sortie en caractères non latins plante en cp1252 → forcer UTF-8 (errors=replace).
  • Saturation du poste (outil lent, timeout) n'est pas un bug applicatif : basculer d'outil d'abord.
  • Variable PYTHONHOME héritée : casse socket/paramiko de façon silencieuse.
  • Un exit 0 sans effet est un bug (R71) : vérifier l'effet, pas le code.

Anti-patterns

Changer plusieurs choses à la fois. Deviner sans observer. Réessayer la même approche trois fois (R22). Corriger le symptôme et fermer.

Changelog

  • 2026-09-07 — 1.1 : R22/R48/R51 définies en une ligne ; chemins vault remplacés par « log d'erreurs du projet » ; noms de scripts privés retirés ; exemple timer systemd ajouté ; frontmatter normalisé.
  • 2026-07 — 1.0 : version initiale.