mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-06-28 01:53:40 +02:00
docs(knowledge): capitalisation workflow + ux — intégration du triage local (mai-juin 2026)
Triage et intégration des propositions workflow et UX du buffer 95_a_capitaliser.md. WORKFLOW : - risques/story-tracking.md : 24 risques de suivi de story (enabler AC non-bloquant, tests plumbing vs scénario, reformat hors scope, xit sans story de suivi, re-scope mid-PR, statut migré non vérifié, périmètre auto-déclaré vs git diff, composant/page livré sans câblage — reciblages venus de backend #21 et frontend #257) - patterns/general.md : audit cartographique pré-chantier, Go/No-Go par lot, sub-agent review fresh-context, sweep read-only délégué (#156), revue adverse de spec, audit-first migration UX (domaine amorcé — était vide) : - patterns/general.md : 9 patterns (mount-based read, fiche détail single-scroll, FAB étendu, ligne de contexte filtres, état read-only caché, avatar par hash, audit a11y touch targets) - risques/general.md : 5 risques (bouton retour dans ScrollView #108, lien sans handler, wording cross-écran divergent, token sans détection, padding multi-écrans) - READMEs ux/workflow mis à jour Vérifié : aucun doublon d'ancre/titre, fichiers racine 40_/90_ non modifiés (propositions réservées pour validation séparée). Source 95_ non purgée (purge en fin de capitalisation). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
MaksTinyWorkshop
@@ -6,4 +6,4 @@ Risques liés au process de développement, aux agents BMAD, et au tracking des
|
||||
|
||||
| Fichier | Domaine | Entrées clés |
|
||||
|---------|---------|--------------|
|
||||
| `story-tracking.md` | BMAD, agents, story completion | Story "completed" avec tâches ❌, story "done" sans fichiers source dans File List, statut BMAD correct mais sections narratives obsolètes, stratégie de fix d'une suite E2E qui rote en masse |
|
||||
| `story-tracking.md` | BMAD, agents, story completion, scope, traçabilité, tests | Story "completed" avec tâches ❌, story "done" sans fichiers source, statut BMAD vs sections narratives, fix d'une suite E2E en masse, enabler avec AC coûteux non-bloquant, tests "plumbing" vs "scénario", "test forwarding" vs intersection, reformat hors scope, code de "préparation" non testé, "fix CI" devient refacto, `xit`/skip sans story de suivi, AC déféré vers story fantôme, re-scope mid-PR, writer+reader décorrélés, écart AC "à confirmer", enabler sans traçabilité, statut "X% migré" non grepé, bump dépendance non déclaré, statut done sans commit, suppression feature + artefacts orphelins, lot soudé = commit groupé, review = suite complète, infra VERSIONNÉ vs EXÉCUTÉ, auto-déclaration de périmètre, Completion Notes vs code, doublon d'emplacement story, composant sans point d'entrée UI, page sans câblage navigation |
|
||||
|
||||
@@ -339,3 +339,505 @@ source_projects: [app-alexandrie, app-template-resto, RL799_V2]
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-story-enabler-ac-couteux-non-bloquant"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-test-ac-plumbing-vs-scenario"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-test-forwarding-vs-intersection"></a>
|
||||
## "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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-reformat-hors-scope"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-preparation-non-testee"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-fix-ci-devient-refacto"></a>
|
||||
## "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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-xit-supprime-couverture-critique"></a>
|
||||
## `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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-ac-defere-story-fantome"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-rescope-mid-pr-renommer"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-writer-reader-decorreles"></a>
|
||||
## "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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-ecart-ac-a-confirmer-jamais-confirme"></a>
|
||||
## É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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-story-enabler-sans-tracabilite"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-statut-migre-non-verifie-grep"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-bump-dependance-non-declare"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-statut-done-sans-commit"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-suppression-feature-artefacts-orphelins"></a>
|
||||
## 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É <story>") 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-lot-soude-revue-commit-groupes"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-review-suite-complete-pas-sous-ensemble"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-story-infra-versionne-vs-execute"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-auto-declaration-perimetre-non-verifiee"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-completion-notes-vs-code-deux-options"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-doublon-emplacement-story-create-vs-dev"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-composant-livre-sans-point-entree-ui"></a>
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-page-module-sans-cablage-navigation"></a>
|
||||
## 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)
|
||||
|
||||
Reference in New Issue
Block a user