LifePlay-Revival/Docs/Migration/19_Plan_Outillage_Debug.md

# 19 — Plan d'outillage debug (pilotage)

> Plan de lot révisé (game manager + senior). Procédure opérationnelle et mesures :
> [`18_Build_Debug.md`](18_Build_Debug.md). Skill agent :
> [`.cursor/skills/lifeplay-debug-build/`](../../.cursor/skills/lifeplay-debug-build/).
> Protocole lots : [`10_Protocole_Operations.md`](10_Protocole_Operations.md).

**État :** gates I0–I6 mesurés (voir §4 et relevés dans `18`). Prochain lot d'optimisation
proposé : **G6** (pas O10 en premier) — décision dans `18` § mesures.

---

## 1. Brief production (game manager)

### Mission

Livrer une **capacité de mesure reproductible** (pipeline + preuves), pas une optimisation joueur. Après ce lot, l'équipe peut décider *quoi* corriger (G6 à-coups, O10 physique) avec des chiffres, pas au feeling.

### Succès (Definition of Done globale)

Le lot est **terminé** seulement si :

1. Un tiers (ou un agent futur) peut packager DebugGame/Development et lancer sessions A/B/C **sans scripts hors dépôt**.
2. Trois jeux de preuves archivés (`Dbg-I4`, `Dbg-I5`, `Dbg-I6`) sous `D:\Game\LifePlay_Backup_5.5\`.
3. Une note chiffrée classe les priorités suivantes (G6 vs O10 vs autre) — **décision**, pas encore le fix.
4. Shipping **inchangé** en comportement joueur (`IncludeDebugFiles=False`, pas de coût runtime Shipping).
5. Skill + `18_Build_Debug.md` alignés sur le livré.

### Hors scope (explicitement)

| Inclus | Exclu jusqu'à preuves I4–I6 |
|---|---|
| Scripts packaging / lanceurs / collecte | Optimisation GI / timers / async load |
| Sous-système debug non-Shipping | Refonte collisions ville / LOD / morphs |
| Doc + skill | Montée UE 5.8 (préparer seulement la portabilité) |
| Mesure G6 / Physics | Intégration Tracy / Optick / ASAN / ImGui |
| Outils gratuits documentés | Builds Shipping « debug » pour joueurs |

### Priorité joueur (pourquoi ce lot)

| Signal existant (O0/O9) | Impact ressenti | Ce lot livre |
|---|---|---|
| À-coups GameThread (G6) | Stutters irréguliers | Preuve nommée → backlog fix priorisé |
| Physics ~463 Mo (O0) ; ~172 Mo session B post-O9 | Risque machines modestes | Chiffre Physics + CVD → backlog O10 |
| Régime 16,7 ms | OK aujourd'hui | Garde-fou non-régression (I6) |

**Règle produit :** ne pas ouvrir un lot d'optimisation tant que I4 (hitches) **et** I5 (mémoire) n'ont pas leurs gates verts.

### Effort et dépendances (ordre de grandeur)

| Phase | Effort estimé | Qui | Dépendance |
|---|---|---|---|
| I0 skill | 15 min | Agent | — |
| I1 scripts + 1er cook DebugGame | 0,5–1 j (+ cook long) | Agent ; cook machine | UE 5.5, Content/Heavy dispo |
| I2 C++ + compile / smoke | 0,5 j | Agent | I1 ou Editor Development pour smoke |
| I3 doc + sync skill | 0,25 j | Agent | I1–I2 stabilisés |
| I4 / I5 / I6 playtests | 3× ~20–30 min jeu + analyse | **Utilisateur** joue ; agent archive/analyse | Builds prêtes |

**Chemin critique :** temps de cook DebugGame + disponibilité playtest humain.

### Risques production

| Risque | Impact | Mitigation |
|---|---|---|
| Cook DebugGame très long / échec | Bloque I1 | Smoke I2 en Editor d'abord ; `-SkipBuild` / iterate ; un seul cook DebugGame pour I4–I5 |
| Confusion DebugGame vs Dev sur les ms | Fausses régressions | Dual-build documenté ; I6 = Development only vs O0 |
| Instrumentation fuit dans Shipping | Perf / logs joueur | `#if !UE_BUILD_SHIPPING` strict ; pas de changement `DefaultGame.ini` Shipping |
| Scope creep « on corrige GI tout de suite » | Lot interminable | Hors scope ; nouveau lot après I6 |
| Trace Insights trop lourde | Machine saturée (déjà vu O9) | Trace courte ciblée ; channels limités ; bookmarks |
| Playtest non standard | Mesures incomparables | Scénario O0 figé 15 min ; même type de save |

### Gouvernance

- Protocole lots : [`10_Protocole_Operations.md`](10_Protocole_Operations.md) (tag, snapshot, journal).
- Skill obligatoire : [`.cursor/skills/lifeplay-debug-build/`](../../.cursor/skills/lifeplay-debug-build/).
- **Go / No-Go** à chaque gate In : critères verts ou stop + re-mesure.
- Commit : uniquement si demandé ; un sous-lot = un objectif mesuré.

---

## 2. Brief technique (senior gameplay / engine)

### Principes

1. **Zero cost Shipping** — tout debug derrière `!UE_BUILD_SHIPPING` ; flags CLI opt-in.
2. **Réutiliser** `ULPSessionLogSubsystem` patterns (`FParse`, `FAutoConsoleCommand`, `FName` categories).
3. **Pas de modification Blueprint GI** dans ce lot — C++ subsystem + ModdingExtra hotspots only.
4. **DebugGame rare** — un cook pour plongée ; itération code en Editor/Development.
5. **Portable 5.8** — Insights/ChaosVD/CSV + attach process ; pas de plugin profiler tiers.

### Architecture cible

```mermaid
flowchart TB
  subgraph mgmt [DoD_produit]
    Proof[Preuves_A_B_C]
    Decision[Priorite_G6_vs_O10]
  end
  subgraph pipe [Pipeline]
    BuildPs[BuildDebug.ps1]
    Bats[Tools/debug_bats]
    Collect[CollectDebugArtifacts.ps1]
  end
  subgraph runtime [Runtime_non_Shipping]
    LPDebug[ULPDebugSubsystem]
    Named[SCOPED_NAMED_EVENT_LoadTxt_Cache]
    SessLog[ULPSessionLogSubsystem_existant]
  end
  BuildPs --> Bats
  Bats --> LPDebug
  Bats --> SessLog
  Named --> Insights[UnrealInsights]
  LPDebug --> Insights
  Bats --> Collect
  Collect --> Proof
  Proof --> Decision
```

### Dual-build

| Config | Rôle | Comparer ms absolus |
|---|---|---|
| **Development** | Baseline chiffrée / I6 vs O0 | Oui |
| **DebugGame** | Plongée I2/I4/I5 (checks, PDB) | Non |
| **Shipping** | Joueurs | Hors lot |

### Livrables techniques

| Livrable | Contenu clé |
|---|---|
| [`Tools/BuildDebug.ps1`](../../Tools/BuildDebug.ps1) | `-Config DebugGame\|Development`, pas `-nodebuginfo`, stage des bats |
| [`Tools/CollectDebugArtifacts.ps1`](../../Tools/CollectDebugArtifacts.ps1) | `-Lot -BuildDir -Session` → backup |
| `Tools/debug/*.bat` | Sessions A/B/C + bugs/gpu/collision |
| `ULPDebugSubsystem` | Hitch + bookmark + MemSnapshot + CollisionDump |
| Named events | `LoadTxt`, `LPDataCache` |
| [`18_Build_Debug.md`](18_Build_Debug.md) | Procédure + mesures + Agent/skill |

### Sessions de capture

Scénario unique (O0 §5, ~15 min) : save avancée → carte → intérieur → extérieur → multi-PNJ → quit.

| Session | Build | Gate métier |
|---|---|---|
| A | DebugGame | Top contributeurs hitch **chiffrés** |
| B | DebugGame | Physics Mo + CVD ou dump collision |
| C | Development | Non-régression vs O0 (médiane ~16,7 ms) |

Auxiliaires hors chemin critique : bugs / gpu (PIX **ou** RGP) / collision.

### Stack outils (gratuite, pas de trial)

Insights + Memory Insights, CSV/LLM, ChaosVD, RenderDoc, PIX, Radeon RGP/RMV, µProf, VS Diagnostics.  
Écartés : Tracy, Optick, ASAN, Superluminal, Nsight par défaut (machine AMD).

Détail : [`.cursor/skills/lifeplay-debug-build/reference.md`](../../.cursor/skills/lifeplay-debug-build/reference.md).

### Pièges techniques connus

- Jamais `-csvCaptureFrames` (crash RHI).
- Mesurer packaged, pas Editor `-game`, pour I6.
- Shipping `NO_LOGGING` — ne pas s'y fier pour l'analyse.
- Traces Insights lourdes : rester court + bookmarks.
- I6 **sans** `-LPHitchLog` (overhead off by default).

---

## 3. Skills (obligatoire agent)

| Skill | Usage |
|---|---|
| [`SKILL.md`](../../.cursor/skills/lifeplay-debug-build/SKILL.md) | Lire **avant** tout code (I0) |
| [`reference.md`](../../.cursor/skills/lifeplay-debug-build/reference.md) | Flags, chemins, mapping symptôme→outil |

Ne pas diverger (mega-lanceur, Tracy, rebuild DebugGame systématique) sans maj skill + ce plan.

---

## 4. Planning itératif mesurable

### Règle de sortie

> On ne quitte **In** que si **tous** les critères de mesure sont verts.  
> Code sans artefact / impression en jeu = **rouge**.  
> Rouge → corriger → **re-mesurer**. Pas de skip vers In+1.

```mermaid
flowchart LR
  I0[I0] --> I1[I1]
  I1 --> G1{Gate}
  G1 -->|non| I1
  G1 -->|oui| I2[I2]
  I2 --> G2{Gate}
  G2 -->|non| I2
  G2 -->|oui| I3[I3]
  I3 --> G3{Gate}
  G3 -->|non| I3
  G3 -->|oui| I4[I4]
  I4 --> G4{Gate}
  G4 -->|non| I4
  G4 -->|oui| I5[I5]
  I5 --> G5{Gate}
  G5 -->|non| I5
  G5 -->|oui| I6[I6]
  I6 --> G6{Gate}
  G6 -->|non| I6
  G6 -->|oui| DoD[DoD_lot]
```

### Statut des gates

| Itération | Objectif | Gate (résumé) | Statut |
|---|---|---|---|
| I0 | Skill | Procédure partagée | Fait |
| I1 | Pipeline scripts | Build + Collect smoke | Fait |
| I2 | `ULPDebugSubsystem` | Hitch / bookmark / MemSnapshot | Fait |
| I3 | Doc 18 + skill sync | Doc = réalité | Fait |
| I4 | Session A | utrace + hitches chiffrés G6 | Fait — voir `18` |
| I5 | Session B | Physics Mo + CVD | Fait — voir `18` |
| I6 | Session C vs O0 | Médiane ≤ 17 ms, hitches | Fait — voir `18` |

### Détail des itérations

#### I0 — Alignement

- **Owner :** Agent  
- **Mesure :** skill lu ; scope hors Tracy/mega-lanceur confirmé  

#### I1 — Pipeline (P0 technique)

- **Livrables :** `BuildDebug.ps1`, `CollectDebugArtifacts.ps1`, bats  
- **Gate :** UAT DebugGame OK + exe + bats staged + Collect smoke → backup non vide  

#### I2 — Runtime debug (P0 technique)

- **Livrables :** `ULPDebugSubsystem` + named events ; Shipping-safe  
- **Gate :** compile clean ; hitch log ; Bookmark ; MemSnapshot non vide  

#### I3 — Doc / skill = réalité

- **Gate :** noms bats/flags identiques doc↔skill↔Tools ; section Agent ; piège CSV documenté  

#### I4 — Mesure G6 hitches (P0 produit)

- **Owner :** Utilisateur (jeu) + Agent (analyse)  
- **Gate :** `.utrace` ; bookmarks/hitch alignés ; top contributeurs avec ms/% ; Collect OK  
- **Livrable décision :** causes candidates classées  

#### I5 — Mesure Physics / fuites (P0 produit)

- **Gate :** Physics Mo ; MemReport ; CVD ou CollisionDump ; delta mémoire ; Collect OK  

#### I6 — Non-régression Development

- **Gate :** CSV ≥1×9000 frames ; LLM ; tableau vs O0 ; médiane ≤17 ms (±1) ou écart causé ; Collect OK  
- **Sans** `-LPHitchLog`  

### Après DoD

Lots suivants (chacun avec baseline avant/après) :

1. **Fix G6** (étalement `ExecuteUbergraph_GI` / `City`, `PopulateRaws`) — priorité décidée en I4/I6  
2. O10 collisions / trimesh — après G6  
3. Montée 5.8 — réutiliser cette pipeline  

---

## 5. Critères d'acceptation (checklist manager)

- [x] Aucun changement comportement Shipping joueur  
- [x] Scripts versionnés ; plus de dépendance à `LifePlay_profil_O0.bat` hors repo  
- [x] I4 + I5 + I6 verts avec backups  
- [x] Décision écrite G6 vs O10 (priorité prochain lot) — dans [`18_Build_Debug.md`](18_Build_Debug.md)  
- [x] Skill + doc 18 synchronisés  
- [ ] Temps cook / playtest consigné au journal (`Journal_Modifications.md`) si publication du lot  

---

## 6. Ordre d'exécution (référence)

1. I0 skill  
2. I1 scripts ; cook DebugGame  
3. I2 C++ ; recook DebugGame si besoin  
4. I3 doc + sync skill  
5. I4 → gate → I5 → gate → I6 → gate  
6. Revue DoD + proposition du prochain lot d'optimisation