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.mdcowork-plugins/tk-dev-discipline/skills/debugging-and-error-recovery/SKILL.md
GitHubDé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)
- Reproduire de façon fiable et minimale (commande et contexte exacts). Non reproductible →
instrumenter d'abord (→
observability-and-instrumentation). - 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). - Une hypothèse falsifiable à la fois : « si X, alors je verrais Y » → tester Y.
- Bissection : réduire la surface (dry-run,
git bisect, isoler le sous-script) jusqu'au point de bascule. - Corriger la cause, pas le symptôme ; vérifier qu'aucune autre branche n'en dépendait.
- Prouver : rejouer le cas + un cas voisin (régression).
- 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 ».
systemctl list-timers --all | grep veille→ le timer existe,LASTdate d'il y a deux jours,NEXTàn/a: il ne se réarme pas.systemctl status veille.service→inactive (dead), dernier résultatexit-code.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.- Hypothèse : le virtualenv a été recréé sans la dépendance →
ls <venv>/lib/*/site-packages | grep paramiko→ absent. Confirmé. - 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-timersaffiche à nouveau unNEXT. - Entrée au log d'erreurs : « timer muet ≠ timer cassé : lire
statuspuisjournalctlavant 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
PYTHONHOMEhé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.