_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-06-25 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

---

Statut BMAD correct mais sections narratives obsolètes

Risques

• Une story peut afficher Status: done ou review tout en conservant des sections narratives (Story Completion Status, Completion Notes) qui contredisent le statut courant
• Le reviewer lit alors un fichier BMAD incohérent : seul le champ Status a été mis à jour, pas le récit qui résume l'état réel de la story
• Risque d'accepter une story dont les notes décrivent un état antérieur (génération de contexte) plutôt que l'implémentation finale

Symptômes

• Status: done mais Story Completion Status mentionne encore ready-for-dev
• Completion Notes décrivant une simple génération de contexte au lieu de l'implémentation réalisée
• Contradiction entre Status, Senior Developer Review et Change Log

Bonnes pratiques / mitigations

• En code review, recroiser systématiquement Status, Story Completion Status, Completion Notes, Senior Developer Review et Change Log : ces cinq sources doivent raconter le même état

• Règle : toute transition BMAD (ready-for-dev → in-progress → review → done) doit mettre à jour aussi les sections narratives qui résument l'état de la story, pas seulement le champ Status

• Traiter une divergence narrative comme un signal de doute sur la complétion réelle, pas comme un simple oubli cosmétique

• Contexte technique : BMAD / workflow agent — app-alexandrie 01-04-2026

---

Story enabler avec AC coûteux non-bloquant

Risques

• Une story "foundations" / "infrastructure" reste in-progress des semaines/mois alors que les stories métier qu'elle débloquait sont toutes livrées
• Le sprint-status est pollué durablement, la vraie progression est masquée

Symptômes

• Story enabler in-progress depuis > 14 jours ; ≥ 2 epics métier postérieurs en done/in-progress ; la majorité des AC de l'enabler sont cochés (preuve par les faits que l'AC coûteux n'était pas bloquant)

Bonnes pratiques / mitigations

• Correction rétroactive : identifier les AC réellement bloquants (les epics suivants ont-ils pu être livrés sans ?), clore l'enabler en done avec Completion Note de dérogation, extraire les AC déférés vers une story enabler hors-epic métier (epic-infra/...).

• Prévention : au sizing, appliquer le test "si cet AC n'était pas livré, pourrais-je démarrer la story 1.2 ?" → si oui, c'est une story séparée. CI mobile E2E (Maestro/Detox) Android+iOS = toujours une story enabler séparée (coût runner macOS + flakiness).

• Contexte technique : BMAD — app-alexandrie 13-05-2026 (story 1.1 bloquée 68 jours par AC4 CI Maestro)

---

Tests d'AC en mode "plumbing" plutôt que "scénario"

Risques

• Un AC de seuil ("au 4e", "au 21e") est testé en mockant directement la valeur de retour (incrWithExpireAt.mockResolvedValue(4)) au lieu de simuler le parcours réel
• Régression silencieuse si la limite change (le mock continue de mentir) ou si l'incrément se casse (l'INCR n'est jamais appelé)

Symptômes

• Le test valide le code d'erreur (POST_QUOTA_EXCEEDED) mais PAS que 1+2+3 passent et que 4 est rejeté

Bonnes pratiques / mitigations

• Pour un AC de seuil, le test e2e doit : (1) simuler un compteur qui incrémente réellement (mockImplementation avec map d'état, pas mockResolvedValue constant) ; (2) effectuer les N appels + le N+1 ; (3) vérifier que les N premiers passent ET le N+1 est rejeté ET (si applicable) que la compensation a décrémenté.

• Contexte technique : BMAD / Redis quota — app-alexandrie 13-05-2026 (story 8.4)

---

"Test forwarding" confondu avec "test intersection"

Risques

• Une task qui revendique tester une combinaison de filtres / un AND backend n'a comme seul test qu'un mock service client vérifiant que les params transitent
• Refacto futur = régression silencieuse de l'intersection

Symptômes

• expect(mockService).toHaveBeenCalledWith(token, { A: true, B: ['x'] }) → prouve uniquement que le store forward, PAS que le backend fait le AND

Bonnes pratiques / mitigations

• Pour toute intersection/combinaison logique serveur, exiger un test e2e backend avec seed couvrant les 4 quadrants : match (A && B), A seul, B seul, ni l'un ni l'autre — vérifier que seul "match" remonte.

• Bonus discriminant AND vs OR : un filtre B incompatible doit renvoyer items=[].

• Review : pour chaque task "combinaison X+Y testée", ouvrir le test et vérifier qu'il SEED des données différenciées et ASSERT le filtre, pas le forwarding.

• Contexte technique : BMAD — app-alexandrie 14-05-2026 (story 11.3)

---

Reformat / changement de fichiers hors scope dans un commit de story

Risques

• Une story embarque silencieusement un reformat prettier ou un changement sur des fichiers non listés (ex. ~32 fichiers, ~2400 insertions de pur reformatage)
• Une régression réelle se noie dans le bruit ; surface de merge conflict énorme ; diff de revue faussé

Symptômes

• git status --porcelain / git diff --stat montrent des fichiers absents de la File List ; un prettier --write . ou un auto-format on save a fait dériver le scope

Bonnes pratiques / mitigations

• Règle : "un commit de story = la File List ± 0 fichier". Avant tout commit : vérifier git status --porcelain + git diff --stat ; tout fichier non listé → (a) l'ajouter à la File List avec justification, soit (b) git checkout HEAD -- <files> avant commit.

• Pour un reformat global voulu : story chore dédiée (chore/prettier-pass) sur sa propre branche.

• Contexte technique : BMAD / prettier — app-alexandrie 13-05-2026 (story 10.1)

---

Code de "préparation" non testé (anticipation des stories suivantes)

Risques

• Une story implémente du code spéculatif pour les stories suivantes ("préparation Story X.Y", "déjà câblé pour la suite") sans tests pour ces chemins
• Si la story suivante change de design, le code mort traîne

Symptômes

• Dev Agent Record contient "Préparation Story X.Y" ; des branches logiques if (opts.x) n'ont aucun test

Bonnes pratiques / mitigations

• Règle : toute branche logique introduite doit avoir AU MOINS un test l'adressant, même si la story qui l'utilisera arrive plus tard. Sinon on n'introduit pas le code maintenant (YAGNI strict).

• Review : compter les tests couvrant chaque if (opts.x) du nouveau code. Tests = AC, pas plus, pas moins.

• Contexte technique : BMAD — app-alexandrie 14-05-2026 (story 11.1)

---

"Fix CI" qui devient un refacto architectural

Risques

• Une story enabler (CI, deploy, infra) déclare un scope limité (5 fichiers) ; au premier run CI des steps préexistantes échouent ; le dev débloque le pipeline dans la même branche en touchant 40-70 fichiers sous un commit massif "fix(ci): débloquer pipeline"
• La File List ment, le commit message ment (un "fix lint" cache une refacto DI), les enablers parallèles deviennent ambigus, les rétros perdent leur valeur

Symptômes

• Un commit "fix CI" touche > 10 fichiers / plus d'un module / des fichiers de production (pas seulement tests/config)

Bonnes pratiques / mitigations

• Option A (préférée) : stop, créer une story sœur infra-N+1, traiter sur branche séparée puis cherry-pick — ou conditionner la step CI cassée et déférer.

• Option B (acceptable) : tout faire dans la branche MAIS commits séparés (1 = scope original, 1 = "fix lint préexistant", 1 = "refacto DI" message clair) + documenter l'extension de scope dans le Change Log.

• Option C (interdite) : commit géant unique "fix CI". Si déjà commis : créer rétroactivement les stories sœurs (status done immédiat + File List pointant vers le commit géant).

• Détection review : un "fix CI" qui touche > 10 fichiers ou > 1 module → exiger un re-split ou une story rétroactive avant merge.

• Contexte technique : BMAD / CI — app-alexandrie 20-05-2026 (infra-1, 5 → 73 fichiers)

---

xit / skip qui supprime de la couverture critique sans story de suivi

Risques

• Un test e2e est marqué xit avec un commentaire xit-reason: honnête, mais la couverture du comportement critique disparaît
• Le commentaire donne l'illusion d'avoir tracé la dette ; aucun outil ne signale qu'un comportement n'est plus couvert

Symptômes

• xit('bloque une écriture community avec session PENDING (423)') avec un xit-reason: qui ne cite aucune story de restauration

Bonnes pratiques / mitigations

• Tout xit/skip doit déclencher soit (a) un fix immédiat avec setup ad-hoc (souvent 10-30 lignes de mock dynamique), soit (b) la création d'une story dédiée explicite qui le restaure.

• Le commentaire doit citer la story qui le ressuscitera (xit-reason: HealthModule retiré, restauré par story infra-4).

• Un xit sans story de suivi nommée = blocker en code review.

• Contexte technique : BMAD / e2e — app-alexandrie 20-05-2026 (infra-5)

---

AC déféré vers une story fantôme

Risques

• Un AC est marqué [DEFERRED] avec référence à une story qui n'existe pas dans le tracking → l'AC est "tracé" mais en réalité perdu

Symptômes

• [DEFERRED AC5] ... (story infra-1-phase-2) où infra-1-phase-2 n'existe pas dans _bmad-output/ ni dans sprint-status.yaml

Bonnes pratiques / mitigations

• Ne JAMAIS déférer un AC vers une story inexistante. Si on défère, créer immédiatement la story cible (titre + AC repris + status ready-for-dev) et l'ajouter à sprint-status.yaml.

• Détection review : grep DEFERRED|TODO|à faire dans dans la story et vérifier que les références pointent vers des fichiers existants.

• Contexte technique : BMAD — app-alexandrie 21-05-2026 (infra-5/infra-6)

---

Re-scope mid-PR — renommer AVANT de merger

Risques

• Une story/PR change de scope en cours de route mais le titre PR, le nom de fichier story et la clé sprint-status gardent l'ancien intitulé
• Le titre de PR se propage dans le merge commit et le displayTitle de TOUS les runs CI — historique GitHub durablement trompeur, non corrigeable après merge

Symptômes

• Code et corps de la story re-scopés, mais slug infra-7-reactivation-… qui contient en réalité un "retrait"

Bonnes pratiques / mitigations

• Checklist re-scope (les quatre ensemble, AVANT le merge) : titre PR + nom de fichier story (git mv) + clé story_key dans sprint-status.yaml + corps de la story.

• Contexte technique : BMAD / CI — app-alexandrie 22-05-2026 (infra-7)

---

"Writer + reader" décorrélés dans une feature à état partagé

Risques

• Une feature reposant sur un store / event bus / queue partagée nécessite DEUX intégrations (writer qui produit l'état, reader qui le consomme) ; si seul l'un est livré, l'AC est cassé alors que toutes les subtasks sont cochées
• Les tests unitaires en isolation passent (store + bouton OK séparément) ; l'intégration ne marche pas car personne n'alimente le store

Symptômes

• Store créé + spec verte, reader appelle lastRoutes[tab], mais le writer manque dans _layout.tsx → lastRoutes reste {} à vie

Bonnes pratiques / mitigations

• À la rédaction de story : nommer explicitement les DEUX callsites ("créer le store" + "brancher le writer dans X" + "brancher le reader dans Y").

• Au dev : un test d'intégration minimal exerçant writer→reader.

• À la review : grep le nom de l'action mutator (setLastRoute, enqueue, publish). Si UN SEUL match (= le store lui-même), la feature est cassée même si toutes les tâches sont cochées.

• Contexte technique : BMAD — app-alexandrie 28-05-2026 (IA-v2.8)

---

Écart AC ↔ implémentation "à confirmer" qui n'est jamais confirmé

Risques

• Un dev s'écarte d'un AC pour une raison légitime, documente l'écart dans les Completion Notes mais ne met PAS à jour l'AC → l'AC reste formellement non respecté et l'écart sera oublié à la prochaine relecture

Symptômes

• AC dit "CTA vers /(tabs)/feed" alors que le code pousse /(tabs)/explore, avec une note "cosmétique, à confirmer"

Bonnes pratiques / mitigations

• Documenter dans Completion Notes ne suffit PAS. Amender l'AC lui-même avec justification inline (l'AC est le contrat) OU créer un follow-up daté ("à confirmer d'ici 2026-XX-XX, sinon AC réécrit").

• Garde-fou : "écart à confirmer" = finding MEDIUM ; la review doit trancher, pas laisser vivre l'ambigu.

• Contexte technique : BMAD — app-alexandrie 29-05-2026 (ux-cleanup-4)

---

Story (enabler) sans sections de traçabilité

Risques

• Une story dont les AC contiennent une checklist ("vérifier écran par écran", "smoke 5 écrans") est livrée sans Dev Agent Record, File List ni Change Log (fichier resté Status: draft)
• La review ne peut pas distinguer "pas fait" de "fait mais non documenté" → pression à passer en done sans preuve, ou revue manuelle linéaire (coût ×10)

Symptômes

• 14 commits livrés, 0 trace structurée dans la story ; AC checklist non prouvables sans reconstitution a posteriori

Bonnes pratiques / mitigations

• Toute story à AC-checklist doit comporter dès le draft : Dev Agent Record (tableau par phase commit), File List (ou pointer git diff --name-only), Change Log chronologique, et une checklist par AC avec statut (✓/⚠️/❌) par item.

• Garde-fou Bob/SM avant ready-for-dev : la story expose-t-elle ces 4 sections (au moins en placeholder) ?

• Contexte technique : BMAD — app-alexandrie 29-05-2026 (ux-cleanup-8)

---

Statut "✅ X% migré" non vérifié par grep en fin de story

Risques

• Le rapport d'audit de début de story ("110 occurrences") est repris tel quel dans le README final sans re-grep → le statut ment par optimisme (17 résiduelles)
• Un futur dev fait confiance au statut et n'audite plus jamais

Symptômes

• README "✅ 110 occurrences remplacées" alors qu'un grep serré en révèle 17 résiduelles

Bonnes pratiques / mitigations

• Ajouter en fin de workflow de migration un step "audit de vérification" : grep après migration DOIT être ≤ 0 (ou documenter chaque exception en code). Le statut README doit refléter ce grep, pas le rapport initial. Si 17 résiduelles → écrire "100/117 (85 %) migrées, 17 documentées".

• Contexte technique : BMAD / migration — app-alexandrie 30-05-2026 (ux-cleanup-12)

---

Bump de dépendance non déclaré dans une story

Risques

• Une story bumpe package.json / pnpm-lock.yaml "en passant" sans le déclarer dans la File List ni les Dev Notes → pollution du commit, surprise du reviewer, risque silencieux sur d'autres stories utilisant la lib

Symptômes

• Story "a11y touch targets" qui bumpe react-native-reanimated ; le reviewer le découvre en grep

Bonnes pratiques / mitigations

• Bump nécessaire au scope → le déclarer (Dev Notes/Risques + File List). Bump opportuniste → story chore dédiée ou justification explicite. Changement de pinning (exact → ~/^) → décision d'archi méritant une mention explicite ou une story dédiée.

• Garde-fou : le reviewer doit pouvoir grep package.json dans le diff et tracer chaque ligne modifiée.

• Contexte technique : BMAD — app-alexandrie 31-05-2026 (ux-cleanup-14/17)

---

Statut done/review non atomique avec un commit Git pushé

Risques

• Une story est marquée done/review dans sprint-status.yaml AVANT que son code soit commité/pushé : statut trompeur (WIP local cru en prod), perte si rollback d'une story partageant un fichier, tracking story → commit cassé
• Cas subtil : fichiers cœur jamais git add (untracked discrets ??) alors que tests/lint/typecheck passent via le filesystem → repo orphelin, prod down

Symptômes

• sprint-status.yaml dit done mais git log --grep "story-name" ne retourne aucun commit pushé
• git status montre des ?? non vus (concentration sur les M)

Bonnes pratiques / mitigations

• Ordre atomique : implémenter (in-progress) → tests/lint/typecheck verts → commit isolé → push origin → PUIS changer le statut.

• Stories partageant un fichier : la story #1 doit être commit-push AVANT que #2 ne touche au fichier.

• Garde-fou : à la transition review → done, git status --porcelain ne doit laisser AUCUN ?? dans les répertoires de la story ; chaque "Nouveau fichier" du Dev Agent Record doit passer git ls-files --error-unmatch <path>.

• Contexte technique : BMAD / git — app-alexandrie 31-05-2026 (ux-cleanup-17/18/22)

---

Suppression de feature et artefacts de planning orphelins

Risques

• Une story SUPPRIME une feature ; le code est propre mais les artefacts de planning (wireframes, specs UX, PRD) qui la décrivaient "à créer" deviennent des pièges qu'un agent futur rejouera

Symptômes

• Wireframe daté décrit toujours la feature supprimée comme cible (composants, routes, props) ; la code review du code seul ne le détecte pas

Bonnes pratiques / mitigations

• Toute story de suppression doit inclure un AC "cohérence documentaire" : grep le nom de la feature dans _bmad-output/planning-artifacts/ et annoter/invalider (bandeau "ABANDONNÉ ") tout doc qui la décrit encore. Ne pas se contenter du grep dans src/.

• Contexte technique : BMAD — app-alexandrie 02-06-2026 (classroom-0)

---

Lot soudé = revue et commit groupés (contrats partagés)

Risques

• Plusieurs stories d'un lot touchent un MÊME contrat partagé et y ajoutent des champs requis consommés des deux côtés → elles forment une unité de compilation indivisible ; un commit story-par-story ne compile pas

Symptômes

• Au moment de committer seulement les stories revues, le découpage est techniquement impossible (champs de contrat ajoutés par une story non incluse mais référencés par le code inclus)

Bonnes pratiques / mitigations

• Quand plusieurs stories d'un lot modifient le même schéma Zod partagé avec des champs requis : soit (a) reviewer tout le lot et committer en bloc, soit (b) imposer dès le cadrage que les champs partagés soient .optional() tant que toutes les stories ne sont pas mergées (permet le commit incrémental).

• Détecter tôt : deux stories "can-run-with" qui modifient le même fichier de contrat → le découpage commit sera bloqué, l'anticiper au sprint-planning.

• Contexte technique : BMAD / contracts-first — app-alexandrie 05-06-2026

---

Review = suite COMPLÈTE, pas le sous-ensemble de la story

Risques

• Le dev lance des sous-ensembles ciblés (la suite du module touché), pas la suite entière → les fichiers de test transverses/partagés (mocks e2e d'autres modules, gardes d'exhaustivité jumelles) restent périmés et cassent en silence
• Une story qui annonce "e2e 78/78" sans avoir lancé la suite globale donne un faux signal de complétude

Symptômes

• En review, lancer la suite complète révèle des fails dans des fichiers que la story N'A PAS touchés (mock e2e d'un autre module consommant une signature changée, garde "couvre exactement les N types" jumelle non mise à jour)

Bonnes pratiques / mitigations

• Règle review : toujours lancer la suite entière (unit + e2e + mobile), jamais seulement la File List.

• Corollaire dev : après tout changement de signature publique (provider/service) ou ajout d'une valeur d'enum, grep tous les consommateurs de tests + lancer la suite complète avant de déclarer "tests verts".

• Contexte technique : BMAD — app-alexandrie 08-06-2026 (ux-parcours-3, bo-6, ux-parcours-7)

---

Story infra/ops : distinguer VERSIONNÉ de EXÉCUTÉ-SUR-CIBLE

Risques

• Sur une story infra (déploiement, backup, config service externe), l'agent produit des artefacts reproductibles mais ne peut PAS exécuter les gestes sur l'environnement réel (créer le realm, exécuter/TESTER le backup, smoke-test prod)
• Piège : marquer ces sous-tâches [x] parce que la PROCÉDURE est documentée alors que l'ACTION n'a pas eu lieu → la story surestime son achèvement, le geste à plus forte valeur ("restauration TESTÉE") reste un trou non signalé

Symptômes

• Story dit [x] (theme appliqué, smoke-test, restauration testée) alors que la table de preuve du runbook est (à remplir) / [ ]

Bonnes pratiques / mitigations

• 3 états, pas 2 : [x] = versionné/documenté ET vérifiable par l'agent ; [~] = artefact versionné mais exécution cible pending ; [ ] = geste ops non fait.

• Un AC "TESTÉE" (restauration, smoke-test, login réel) n'est JAMAIS satisfait par une procédure documentée — il exige une preuve d'exécution consignée (date/étapes/résultat).

• En review, croiser les [x] de la story avec le runbook ; lister les gestes hors-repo dans un Dev Agent Record dédié. La story reste review (artefacts prêts), done au déploiement réel prouvé.

• Contexte technique : BMAD / Keycloak prod — RL799_V2 15-06-2026 (K1.9)

---

Auto-déclaration de périmètre d'une story (à vérifier contre git diff --stat)

Risques

• Une étiquette "contenu uniquement" / "fix minimal" / "pas de code applicatif" est une CLAIM, pas un fait. Une story ainsi étiquetée peut livrer une refonte UI substantielle (+461 lignes nettes) documentée comme "2 fixes de typage minimaux", avec File List incomplète et "test:frontend vert" alors qu'il est rouge

Symptômes

• Un "fix de typage minimal" qui touche un fichier passant de 274 à 735 lignes — l'écart entre la description et le wc -l est le tell

Bonnes pratiques / mitigations

• Procédure review : (1) identifier le commit de référence (Depends-on/Previous), (2) git diff --stat <ref>..HEAD + working tree, (3) tout fichier > ~50 lignes de delta non listé dans la File List = finding MEDIUM minimum, (4) toute affirmation "suite X verte" = à REJOUER (un fichier de logique partagée qui change de signature casse un test préexistant non mis à jour en silence).

• Quand une refonte se glisse dans une story de contenu : exiger commit séparé + File List fidèle + tests propres.

• Contexte technique : BMAD — RL799_V2 22-06-2026

---

Completion Notes vs code, surtout quand deux options d'implémentation existaient

Risques

• Quand une story propose une approche A et une alternative B, la Completion Notes peut affirmer avoir fait A alors que le dev a silencieusement choisi B (souvent le meilleur choix)
• Un reviewer qui croit la note sur parole rate l'écart ; la prochaine personne partira sur une fausse hypothèse

Symptômes

• Completion Notes "ROLES_X étendu avec 'hospitalier'" alors que le bypass est réalisé autrement (au niveau repo) ; comportement réel correct mais note factuellement fausse

Bonnes pratiques / mitigations

• Pour chaque tâche [x] mentionnant un fichier/symbole précis ("étendu le set X", "ajouté le champ Y"), ouvrir CE fichier et vérifier la présence réelle du changement — ne jamais cocher sur la foi de la note.

• L'écart "note dit A / code fait B" est un finding MEDIUM (doc trompeuse) même quand B est correct : c'est une note à corriger, pas du code à changer.

• Contexte technique : BMAD — RL799_V2 23-06-2026 (v2-5-3)

---

Divergence d'emplacement create-story vs dev-story (fichiers homonymes)

Risques

• create-story génère la story dans l'arborescence sprint sous-dossiée (implementation-artifacts/version-X/<flow>/, committée), mais dev-story écrit un fichier homonyme à PLAT dans implementation-artifacts/ → deux fichiers : l'un committé/vierge, l'autre untracked/rempli (la vraie story)
• Une review peut se baser sur le mauvais fichier ou laisser un doublon désynchronisé

Symptômes

• find <implementation-artifacts> -name '<story-key>*.md' retourne > 1 fichier ; l'un en ready-for-dev/tasks [ ], l'autre en review/tasks [x]/Dev Record rempli

Bonnes pratiques / mitigations

• Avant toute code-review : vérifier l'unicité du fichier de story (find). En cas de doublon, identifier la vraie story (status review/done + tasks cochées + File List), copier son contenu réel vers l'emplacement sprint COMMITTÉ, supprimer l'orphelin plat — préserver l'arborescence sprint comme source de vérité git.

• Contexte technique : BMAD — RL799_V2 23-06-2026 (v2-6-1)

---

Composant "livré" sans point d'entrée dans l'UI (fonctionnalité mort-née)

Risques

• Un composant créé (service + composable + vue + tests) mais non intégré dans aucune page/route est invisible : l'utilisateur ne peut pas y accéder
• Les tests passent (composant présentationnel monté isolément), ce qui masque l'absence d'intégration ; une tâche peut être [x] alors que le composant est orphelin

Symptômes

• SeasonReportView.vue présent, testé, mais non importé dans aucune page ni dans le router

Bonnes pratiques / mitigations

• Checklist revue frontend (si l'une des 3 est non → finding HIGH) : (1) le composant est-il importé dans au moins une page parente ? (2) la page parente est-elle accessible via une route ? (3) existe-t-il un chemin de navigation visible pour l'utilisateur cible ?

• Pattern de correction : intégrer dans la page parente existante (onglet) plutôt que créer une nouvelle page ; ajouter un sélecteur de contexte (saison, période) si besoin.

• Contexte technique : BMAD / Vue — RL799_V2 19-06-2026 (v2-3-1)

---

Page/module livré sans câblage de navigation (dette fonctionnelle invisible)

Risques

• Une page/module peut être 100% fonctionnel (backend gardé, page, service, tests verts, CI verte) et pourtant TOTALEMENT inaccessible faute de câblage navigation
• Classe de bug invisible : aucun test ne vérifie "ce module est atteignable"

Symptômes

• "Je ne vois plus mon module X" alors que tout le code existe et que la CI est verte ; seul le câblage navigation manque

Bonnes pratiques / mitigations

• Maillons à câbler (sur une app multi-surface mobile + desktop, ils sont SÉPARÉS — câbler l'un ne suffit pas) : (1) constante de rôles/permissions partagée + son ré-export (attention export * vs exports explicites) ; (2) route (path + name + meta de garde) ; (3) nav desktop (sidebar) + icône ; (4) nav mobile (liste/computed distincts) ; (5) tout hub/plan/menu de découverte secondaire qui mappe entité→route.

• Détection : à chaque nouvelle page, vérifier qu'une route Y MÈNE et qu'une entrée de nav LA RÉFÉRENCE, sur TOUTES les surfaces. Idéalement un test de garde "toute page de module a une route nommée + une entrée de nav".

• Prévention : la DoD d'un module inclut "accessible depuis la navigation sur mobile ET desktop", pas seulement "page + back + tests".

• Contexte technique : Vue / app multi-surface — RL799_V2 21-06-2026 (Epic v2-4)