_Assistant_Lead_Tech/knowledge/workflow/risques/story-tracking.md

title: Workflow — Risques & vigilance : Story tracking domain: workflow bucket: risques tags: [bmad, story, file-list, review, completion] applies_to: [analysis, implementation, review] severity: high validated_on: 2026-04-07 source_projects: [app-alexandrie, app-template-resto, RL799_V2]

Workflow — Risques & vigilance : Story tracking

Extrait de la base de connaissance Lead_tech. Voir knowledge/workflow/risques/README.md pour l'index complet.

---

Story "completed" avec tâches ❌ auto-déclarées

Risques

• Un agent sette Status: completed alors que son propre Dev Agent Record liste des items ❌ non implémentés
• Le store mobile, service ou tests peuvent être déclarés manquants par l'agent lui-même mais la story semble terminée

Symptômes

• Dev Agent Record contient ❌ store mobile non implémenté mais Status: completed
• Code review découvre des ACs non satisfaits

Bonnes pratiques / mitigations

• Avant de setter Status: completed, vérifier que le Dev Agent Record ne contient aucun ❌

• En cas de doute ou d'item manquant, setter Status: review pour déclencher la code review

• Règle : Status: completed = zéro ❌ auto-déclaré dans le Dev Agent Record

• Contexte technique : BMAD / workflow agent — app-alexandrie 20-03-2026

---

Story "done" sans aucun fichier source dans la File List

Risques

• Un agent peut halluciner la completion d'une story en produisant une note générique sans écrire de code
• La File List ne contient que des fichiers _bmad-output/ mais aucun src/, prisma/, tests/

Symptômes

• Completion note générique du type "Ultimate context engine analysis completed"
• File List réduite à 2 fichiers meta (story file, sprint-status)
• git log --follow src/ ne montre aucun commit lié à la story

Bonnes pratiques / mitigations

• Lors d'une code review, si la File List ne contient aucun fichier source : traiter comme non implémentée

• Vérifier avec git log --follow src/ avant d'accepter le Status: done

• Ne pas faire confiance au status done sans preuve dans le code

• Contexte technique : BMAD / agent Codex — app-template-resto 21-03-2026

---

Story validée avec changements hors périmètre non documentés

Risques

• Le reviewer valide un faux scope ou rejette à tort une story correcte.
• Des changements source non tracés (working tree dirty) peuvent masquer une implémentation partielle ou des effets de bord.

Symptômes

• Tâches [x] et File List propre, mais git status montre des fichiers modifiés hors story
• Aucun bloc "hors périmètre" dans le Dev Agent Record alors que des fichiers non liés ont été touchés

Bonnes pratiques / mitigations

• Si des changements hors story sont présents dans le working tree, documenter un bloc "hors périmètre" explicite dans le Dev Agent Record (liste courte + justification).

• Ne marquer done qu'après clarification de périmètre.

• Règle : le reviewer croise systématiquement git diff --name-only avec la File List avant d'accepter.

• Contexte technique : BMAD / workflow agent — 30-03-2026

---

File List approximative — chemins faux ou fichiers source absents

Risques

• Validation d'une implémentation avec traçabilité mensongère.
• Chemins fictifs dans la File List non détectés si le reviewer ne croise pas avec git.

Symptômes

• File List courte ou générique alors que le diff réel touche de nombreux fichiers source
• Fichier listé avec un chemin qui n'existe pas dans le repo

Bonnes pratiques / mitigations

• Règle review : comparer la File List du Dev Agent Record au git diff --name-only réel.

• Tout fichier source modifié absent de la File List → signaler en MEDIUM.

• Tout fichier listé avec un chemin inexistant en git → signaler en HIGH.

• Contexte technique : BMAD / workflow agent — app-template-resto 31-03-2026

---

Story "review" non alignée avec la réalité du diff

Risques

• La File List, les Completion Notes et les tâches [x] ne reflètent pas la réalité de git diff / git status
• Des régressions de tests passent inaperçues si le statut review est accordé sans croisement avec le diff
• Des fichiers créés dans un commit antérieur (ex: commit de refonte UI) sont listés dans la story sans traçabilité explicite

Symptômes

• git diff --name-only montre des fichiers absents de la File List (ou inversement)
• Completion Notes contenant des déclarations contredites par le diff réel
• Tâches [x] "tests impactés passent" alors que des tests cassent sur des fichiers modifiés dans la story
• Fichiers listés dans la File List absents de git diff HEAD~1..HEAD pour le commit story

Bonnes pratiques / mitigations

• Avant passage en review : comparer File List vs git diff --name-only + git status --porcelain

• Refuser le statut review si un fichier source de la story manque de la File List

• Exiger une section "preuves de validation" quand une tâche mentionne une validation UX/Dev

• Exiger un run de tests sur le périmètre touché, avec mention explicite des échecs non liés

• Si des fichiers sont répartis sur plusieurs commits, mentionner explicitement dans la File List le commit d'introduction de chaque fichier

• Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026

---

Quality gate déclaratif non exécutable

Risques

• Une story impose un gate process (PR template, checklist obligatoire) mais aucun mécanisme de contrôle vérifiable n'existe
• En review, cela crée un faux sentiment de contrôle et laisse passer des PR non conformes

Symptômes

• Story qui déclare un quality gate via documentation/template sans CI check, script de validation, ni evidence review tracée
• AC marqués ✅ sur la base d'un template rempli mais sans preuve d'exécution

Bonnes pratiques / mitigations

• La review doit vérifier au moins un mécanisme de contrôle actionnable (CI check, script de validation, required field policy, ou evidence review tracée)

• Sans ce mécanisme, classer les AC comme PARTIAL et repasser la story en in-progress

• Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026

---

AC dépendante d'une capacité non supportée par le contrat technique

Risques

• Un AC demande un comportement impossible avec le contrat courant (ex: multi-rôles alors que le JWT expose un rôle scalaire)
• Sans clarification explicite dans la story, la review crée des allers-retours et des faux écarts

Symptômes

• AC mentionnant une capacité que le token, le schéma ou l'API ne supporte pas actuellement
• Dev qui implémente un workaround non documenté pour satisfaire l'AC

Bonnes pratiques / mitigations

• Si un AC dépend d'une capacité non supportée par le contrat actuel (token, schéma, API), documenter explicitement la contrainte dans la story

• Marquer la capacité hors-scope tant que le contrat n'est pas migré

• Exiger une note Dev Notes + alignement Tasks/Tests sur cette contrainte

• Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026

---

Tâches [x] validées par tests textuels au lieu de tests comportementaux

Risques

• Une story passe en review avec des tâches [x] dont la preuve repose uniquement sur des assertions textuelles (content.includes(...)) sans exécuter le flux réel
• Les tests de présence textuelle valident des labels mais pas les cibles de navigation, ni les transitions d'état

Symptômes

• Tests qui passent en vérifiant uniquement la présence de chaînes dans les fichiers source
• AC fonctionnels non réellement garantis (toast, mise à jour réactive, soumission) malgré un statut story en review
• Tests content.includes(...) valident des labels mais pas les to/href de navigation

Bonnes pratiques / mitigations

• Toute tâche de test marquée [x] doit inclure au moins un test comportemental exécutable (pas seulement content.includes(...))

• En cas de tests purement textuels, classer la tâche comme non validée et repasser la story en in-progress

• Pour toute AC mentionnant "clic" ou "navigation", imposer une vérification des cibles (:to, href, route name)

• Règle : un test qui ne vérifie que des helpers adjacents ou des chaînes statiques ne peut pas clôturer une tâche d'intégration

• Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026

---

Agents autonomes et dérive des contrats partagés

Risques

• Après une session multi-agents, les types/DTOs sont redéfinis localement dans chaque service au lieu d'utiliser le package shared
• La dérive est détectée uniquement lors d'une review globale de cohérence, pas pendant l'implémentation

Symptômes

• Types définis localement dans apps/frontend/src/services/ au lieu d'être importés depuis packages/shared
• Plusieurs services avec le même type défini indépendamment, avec des divergences subtiles
• Détection : grep -r 'type.*=' apps/frontend/src/services/ | grep -v 'import'

Bonnes pratiques / mitigations

• Inclure dans le prompt d'agent une instruction explicite : "créer les DTOs dans packages/shared AVANT d'écrire le service frontend"

• Ajouter une review globale de cohérence après toute session multi-stories

• Règle review : tout type défini localement qui correspond à un DTO existant dans shared est une régression

• Contexte technique : BMAD / agents autonomes — RL799_V2 07-04-2026

---

Incohérence entre Completion Notes et réalité du code

Risques

• Les dev agents documentent des métriques dans les Completion Notes (nombre de tests, nombre de routes) sans les vérifier en fin d'implémentation
• Le reviewer passe du temps à réconcilier des chiffres qui ne matchent pas

Symptômes

• "20 tests RBAC" revendiqués dans les Completion Notes alors que le fichier test n'en contient que 11
• Route DELETE /api/favorites listée dans le rapport d'audit mais inexistante dans le code

Bonnes pratiques / mitigations

• Avant de passer une story en review, le dev agent doit vérifier que les chiffres dans les Completion Notes correspondent exactement au code

  • grep -c 'test(' fichier.test.ts pour le nombre de tests
  • grep -c 'export' fichier.routes.ts pour le nombre de routes

• Règle : toute métrique dans les Completion Notes doit être vérifiable par une commande simple

• Contexte technique : BMAD / workflow agent — RL799_V2 08-04-2026

---

Story impose une convention absente du code projet

Risques

• Divergence silencieuse entre specification story et implémentation réelle.

Symptômes

• Le dev adapte une convention introuvable sans la tracer dans la story/notes de review.

Bonnes pratiques / mitigations

• Si une convention prescrite n'existe pas dans le repo, documenter explicitement l'adaptation retenue.

• Mettre à jour la story (Change Log / Completion Notes) avec justification et impact.

• Contexte technique : BMAD / traçabilité adaptation story — RL799_V2 15-04-2026

---

Stratégie de fix d'une suite E2E qui rote en masse (post-refactor)

Risques

• Quand un projet enchaîne plusieurs refactors UI/lifecycle sans run E2E entre chaque, on découvre souvent N fails (10-20) d'un coup
• Tentation de fixer fail-by-fail dans l'ordre où ils apparaissent — erreur : on se disperse sur N causes-racines mélangées et chaque commit n'est pas reviewable
• Sans capitalisation immédiate des patterns, on perd le bénéfice de la session pour les futurs refactors

Symptômes

• 13 fails d'un coup après une période de refactor intense
• Tentative de fix fail-par-fail qui produit un commit géant difficile à reviewer
• Capitalisation reportée → patterns oubliés à la session suivante

Bonnes pratiques / mitigations

Process recommandé :

1. Run complet en mode list d'abord : playwright test --reporter=list. On veut la liste exhaustive des fails, pas un comptage one-shot par fichier (qui peut masquer des fails qui apparaissent uniquement quand on lance la suite entière à cause d'effets de bord seed).

2. Catégoriser par cause-racine plutôt que par fichier (cf. knowledge/frontend/risques/tests.md — Tests E2E qui rotent — 6 causes-racines récurrentes) :

   • testid changé sans MAJ tests
   • label métier changé (lifecycle, statut)
   • menu/dropdown conditionnel
   • feature supprimée (query param, route)
   • refactor visuel (texte → icône)
   • cleanup post-test à rendre best-effort

3. 1 commit = 1 cause-racine. Pas "fix 19 fails" en un commit géant. Permet :

   • Review plus simple (chaque commit a un thème clair)
   • Revert chirurgical si une cause-racine s'avère mal diagnostiquée
   • Capitalisation : chaque commit message documente le pattern

4. Validation entre commits : run la suite complète après chaque commit pour savoir avant le push que le commit n'a pas régressé d'autres tests.

5. Capitaliser les patterns à > 2 occurrences : si on voit le même type de fail 3 fois sur 3 fichiers différents, c'est un pattern. Le poser dans knowledge/frontend/risques/tests.md immédiatement, pas plus tard.

Anti-pattern à éviter : "je fixe les 5 fails P1 d'abord, je verrai les P2 après". Si la cause-racine est la même (ex : labels lifecycle v3), on perd 30 min à re-comprendre quand on retourne sur les P2 plus tard. Mieux : grouper par cause-racine, pas par priorité.

Métrique de référence : 19 fails fixés en 4 commits / ~3 h dont 1 h de capitalisation. Effort par fail : ~6 min de fix + 4 min de validation.

• Contexte technique : Playwright / refactor UI — RL799_V2 25-04-2026