Dépannage

Table des symptômes les plus fréquents.

Le registre et la CLI

« Registre corrompu »

Symptôme : node sdlc/sdlc.js status affiche Registre corrompu : .product/sdlc-registry.json.

Cause probable : édition manuelle ayant cassé le JSON, fusion git non résolue, éditeur ayant inséré des caractères BOM.

Remède :

1. git diff .product/sdlc-registry.json pour voir les modifications récentes.
2. Restaurer la dernière version valide : git checkout HEAD -- .product/sdlc-registry.json.
3. Refaire les transitions manquantes via node sdlc/sdlc.js move — jamais en rééditant le JSON.

« Transition refusée : → »

Symptôme : move refuse la transition.

Cause probable : la transition n'existe pas dans schema.js depuis l'état courant.

Remède :

1. node sdlc/sdlc.js check <id> pour voir les transitions autorisées.
2. Si la transition visée n'est pas listée, il manque probablement un passage intermédiaire (ex: BLOCKED puis IN_PROGRESS).
3. Si la transition devrait exister mais est absente, vérifier la version du kernel (git -C .sdeg log -1).

« Verdict NO-GO — transition refusée »

Symptôme : la CLI bloque la transition à cause d'un check automatisé.

Cause probable : un invariant ou un check obligatoire échoue (fichier manquant, contenu non conforme).

Remède :

1. Lire attentivement la ligne ↳ <raison> qui suit le check échoué.
2. Corriger l'artefact pointé.
3. Relancer node sdlc/sdlc.js check <id> pour valider que le check passe.
4. Si et seulement si vous jugez la transition légitime malgré l'échec : --force (le fait que l'appel soit forcé est tracé dans l'historique).

« Parent introuvable »

Symptôme : init fe ou init us refuse la création.

Cause probable : le parent --parent BE-XX n'existe pas, est d'un mauvais type, ou est en état terminal.

Remède :

1. node sdlc/sdlc.js status pour lister les objets disponibles.
2. Corriger l'identifiant de parent.
3. Si le parent est en état terminal (TERMINE, ARCHIVED), l'objet enfant doit être rattaché à un nouveau parent vivant.

Les hooks

« Hook SessionStart semble n'injecter aucun contexte »

Symptôme : l'agent IA n'a pas connaissance de spiral-state.md.

Cause probable :

• Le fichier .product/spiral-state.md n'existe pas.
• Le chemin du hook dans .claude/settings.json est incorrect.
• PowerShell 7 (pwsh) n'est pas dans le PATH.

Remède :

1. Créer .product/spiral-state.md (même minimal).
2. Vérifier : pwsh --version retourne bien 7+.
3. Inspecter .claude/settings.json : le chemin doit être relatif à la racine projet.

« Hook PreToolUse bloque alors que le terme est légitime »

Symptôme : deny sur un fichier HTML pour un terme qui, dans ce contexte précis, est acceptable.

Cause probable : le lint ne connaît pas le contexte — il est volontairement strict.

Remède :

1. Reformuler avec le vocabulaire CODIR (ex: « Dossier COMEX » au lieu de « EHS/LBC »).
2. Si le terme est vraiment indispensable (ex: dans une documentation technique interne), utiliser une extension .md au lieu de .html — le lint ne s'applique qu'au HTML.
3. Si la règle semble inadaptée à votre contexte, ouvrir une issue sur le kernel pour discussion — ne pas désactiver le hook.

« Hook Stop ne crée pas de fichier session »

Symptôme : aucune trace dans .product/.events/ à la fin de la journée.

Cause probable :

• Un fichier session du jour existe déjà (cas nominal — le hook ne recrée pas).
• stop_hook_active est true (évite les boucles, cas nominal).
• .product/.events/ n'est pas inscriptible.

Remède :

1. Vérifier la présence d'un fichier YYYY-MM-DD-*.md dans .product/.events/.
2. Si absent et attendu : vérifier les permissions du dossier.

Git et pre-commit

« Pre-commit bloque mon commit contenant sdlc-registry.json »

Symptôme : le hook pre-commit refuse le commit.

Cause probable : vous avez modifié le registre sans passer par sdlc/sdlc.js move — ou sans événement associé.

Remède :

1. Annuler la modification : git checkout HEAD -- .product/sdlc-registry.json.
2. Refaire la transition via la CLI.
3. Si la modification est une migration de schéma légitime, contourner exceptionnellement avec --no-verify et documenter dans un événement .product/.events/YYYY-MM-DD-migration-schema.md.

Skills et agent

« L'agent propose des move au lieu de les laisser faire par l'humain »

Symptôme : Copilot ou Claude exécute elle-même node sdlc/sdlc.js move.

Cause probable : prompt système mal compris ou surchargé par un contexte conflictuel.

Remède :

1. Interrompre immédiatement.
2. Rappeler explicitement : « Les move sont toujours faits par l'humain après revue. Propose uniquement la commande. »
3. Si l'agent persiste, invoquer #agent-coach-emergent pour recentrer.

« Un skill semble ne pas exister »

Symptôme : #nom-du-skill n'est pas reconnu par Copilot Chat.

Cause probable :

• Le bootstrap n'a pas été relancé après mise à jour du submodule.
• Le fichier .github/prompts/nom-du-skill.prompt.md est absent.
• Copilot Chat a mis en cache une version antérieure.

Remède :

1. ls .github/prompts/nom-du-skill.prompt.md — existe ?
2. Si absent : pwsh .sdeg/scripts/bootstrap.ps1.
3. Redémarrer Copilot Chat (reload VS Code).

« L'agent rédige mais n'écrit pas le fichier »

Symptôme : le skill produit du markdown dans la conversation, sans créer le fichier attendu dans .product/.

Cause probable : l'outil editFiles n'est pas autorisé, ou l'agent n'a pas compris qu'il devait écrire.

Remède :

1. Vérifier le frontmatter du skill : tools: [..., editFiles, ...] doit y figurer.
2. Demander explicitement : « Crée le fichier .product/.epics/BE-I/hypothesis.md avec le contenu ci-dessus. »

Performance et volume

« Le répertoire .product/.events/.tools/ grossit rapidement »

Symptôme : les logs JSONL de hook-pretooluse.ps1 occupent beaucoup de place.

Cause probable : usage quotidien intensif. Normal.

Remède : archiver périodiquement les anciens JSONL (> 3 mois) dans un dossier d'archive, ou les supprimer si la traçabilité longue n'est pas requise. Ne pas les versionner si le projet est public (données de télémétrie).

Voir aussi : Usage quotidien · Mise à jour · Hooks · Invariant sécurité.