runbook: generation chunkee obligatoire (DeepSeek V4 Flash truncation) sur les 3 instances

common/generation-chunkee-taches-volumineuses.md

@@ -0,0 +1,57 @@
+# Generation chunkee obligatoire pour taches volumineuses — DeepSeek V4 Flash
+
+**Date** : 2026-07-02
+**Sphères concernées** : hermes-tt, hermes-nyora, hermes-perso (les 3, déployé comme skill actif)
+
+## Problème
+
+DeepSeek V4 Flash (modèle exclusif de routage Hermes) tronque silencieusement sa
+réponse au-delà d'un certain volume de sortie (`finish_reason=length`). Quand ça
+arrive au milieu d'un appel d'outil (`write_file`, appel API), le JSON de l'appel
+devient corrompu, l'écriture échoue, l'agent retente, le contexte grossit à chaque
+tentative, la session doit être compressée plusieurs fois (perte de précision), et
+au bout de plusieurs échecs l'agent peut se retrouver bloqué 30+ minutes sur un
+outil sans réponse.
+
+## Cas confirmé (02/07/2026, hermes-perso)
+
+Génération d'un document de formation complet (PMI Infinity, 12 sections,
+~2000 mots visés) en un seul payload JSON → 6 échecs consécutifs de troncature
+entre 13h28 et 14h27, 9 compressions de session, agent gelé 30 min sur l'outil
+`process` (iteration 16/90, idle 1800s). Diagnostic confirmé via les logs Docker
+du container `hermes-agent-perso` (warnings `agent.message_sanitization` répétés).
+
+**Résolution** : contenu reconstruit en 3 fichiers intermédiaires distincts
+(quelques sections chacun), assemblés ensuite par du code Python (pas un nouvel
+appel LLM), puis envoyés en un seul appel final à `nyora-doc-api`. Résultat :
+660 mots (échec) → 4200 mots (succès), 12 sections complètes, aucune troncature.
+
+## Règle déployée
+
+Skill actif `generation-contenu-volumineux` installé sur les 3 instances
+(`data/skills/generation-contenu-volumineux/SKILL.md`), déclenché automatiquement
+sur toute tâche de contenu volumineux (formation, rapport complet, document
+>1000 mots, gros JSON/export, batch de données). Le skill impose : découper en
+plusieurs appels d'écriture distincts (jamais un payload unique géant), vérifier
+chaque partie individuellement, assembler par code, puis livrer avec QA visuelle
+(render → screenshot → inspection) avant remise.
+
+## Portée
+
+S'applique à tout type de tâche lourde, pas seulement à la génération de
+documents : rapports d'analyse volumineux, batchs de données, exports, contenu
+de veille, scripts longs. Concerne les 3 sphères (TT, Nyora, Perso) — c'est une
+limite du modèle DeepSeek V4 Flash lui-même, indépendante du domaine métier.
+
+## Signal d'alerte à reconnaître dans les logs
+
+`Response truncated (finish_reason=length)` ou
+`Unrepairable tool_call arguments... replaced with empty object` = ce problème.
+R©agir en repartant sur une construction chunkée, ne pas réessayer la même
+approche en boucle (c'est ce qui a fait empirer la situation le 02/07).
+
+## Voir aussi
+
+`common/skills-concurrents-pdf-docx-pptx-xlsx.md` — problème distinct mais
+découvert le même jour sur les mêmes documents (sélection de skill locale vs
+appel API centralisé).