PD-249 -- Retour d'experience (REX)¶

Date : 2026-02-27 | Story : PD-249 -- Manuel technique SAE consolide Projet : ProbatioVault-doc | Domaine : legal-compliance

1. Synthese¶

PD-249 a produit le premier manuel technique SAE consolide de ProbatioVault : 12 fichiers Markdown, 4620 lignes, 19+ diagrammes Mermaid, couvrant 10 chapitres normatifs + glossaire + integration MkDocs, en reponse au gap GAP-FINAL-001 issu de l'audit PD-244 (documentation fragmentee = bloqueur de certification ISO 14641). La story est la premiere du domaine legal-compliance de type documentaire pur a obtenir le Gate 8 GO en v1 (9.81/10), sans aucun ecart MAJEUR ni BLOQUANT. Les deux principaux enseignements : (1) les projets documentaires exigent que les criteres qualitatifs (verbatim, maintenabilite) soient contractualises quantitativement des la specification, pas laisses interpretatifs ; (2) la validation structurelle (markdownlint + coherence inter-chapitres + YAML nav) constitue un substitut operationnel valide a mkdocs build effectif quand l'environnement n'est pas disponible.

2. Chronologie¶

3. Indicateurs cles¶

4. Points forts¶

1. Gate 8 GO en v1 : Premiere story documentaire legal-compliance a obtenir Gate 8 en une seule iteration (9.81/10). L'approche structurelle (markdownlint 0 erreur + 12/12 CC PASS + 11/11 INV PASS + coherence inter-chapitres) a fourni suffisamment de preuves pour la Gate CLOSURE sans necessite de mkdocs build effectif.

2. Architecture multi-agents par niveaux : La decomposition en 3 niveaux (Niveau 0 : 10 agents paralleles sur les chapitres ; Niveau 1 : glossaire ; Niveau 2 : integration MkDocs) a produit une homogeneite de style remarquable entre les 10 chapitres, a rebours des apprehensions de la Zone d'Ombre ZO-03 identifiee en Gate 5. Le bloc partage cache-first a assure la coherence inter-agents.

3. Matrices de conformite completes : Les matrices ISO 14641:2018 (20 exigences) et NF Z42-013:2020 (23 exigences) ont ete produites avec preuves tracables, reprenant fidelement les scores PD-244 (ISO 77,78%, NF 68,18%), satisfaisant INV-249-04 et INV-249-05 sans ecart en Gate 8.

4. Stubs inter-PD traces avec story destination : PD-251 (verification integrite, statut "En cours Q1 2026") documente avec story destination explicite dans ch06 et ch07. Criticite attenueede MAJEUR a MINEUR en Gate 8 — application directe du pattern issu des retrospectives PD-250/PD-251.

5. Glossaire exhaustif en un passage : 80+ termes definis, 93 acronymes, 5 sections (termes normatifs, techniques SAE, ProbatioVault, reglementaires, acronymes). Aucune insuffisance detectee en Gate 8.

6. Correction proactive ECT-02 : L'incoherence de formule §8.3 (12 vs 11 Conformes) a ete identifiee et corrigee durant la Gate 8 sans nouvel iteration, limitant l'impact a un ecart MINEUR.

5. Points d'attention¶

1. 419 erreurs markdownlint a la sortie de l'implementation : Les agents de niveau 0 ont produit des lignes de plus de 80 caracteres en masse (notamment dans les tableaux). Necessite d'un script wrap-lines.py automatise + corrections manuelles des faux positifs (tableaux, code blocks, URLs). La specification devrait imposer la contrainte markdownlint dans les code contracts.

2. Review ChatGPT superficielle (ECT-01) : La review d'acceptabilite (28 lignes) n'a verifie aucun invariant, aucun code contract, aucun critere d'acceptation — verdict "ACCEPTE AVEC RESERVES" non fonde. La Gate 8 a pu s'appuyer sur le rapport d'acceptabilite Claude mais le principe de validation croisee a ete affaibli. ECT-01 est l'ecart le plus significatif de la story.

3. _build/ gitignore bloqueur non anticipe : Les fichiers produits par les agents dans _build/docs/sae-manual/ n'etaient pas trackes par git (dossier gitignore). Decouverte tardive lors de l'integration. Le plan mentionne _build/ comme repertoire cible mais n'avait pas anticipe ce cas. Solution : placer les fichiers SAE dans docs/sae-manual/ (hors _build/).

4. mkdocs build non execute : L'invariant INV-249-10 (MkDocs publiable) a ete valide structurellement (nav YAML + existence fichiers) mais pas par un build HTML effectif. Limitation acceptee (ECT AMB-02 MINEUR en Gate 8) mais constitue un risque documentaire residuel.

5. claude -p indisponible depuis session active : La confrontation Gate 8 a ete executee via Task agent au lieu de claude subprocess. Solution de contournement operationnelle mais l'isolation du contexte est moins garantie qu'avec unset CLAUDECODE && claude -p.

6. Blocage Xcode license : Un blocage systeme (licence Xcode non acceptee) a interrompu les operations git, necessite une intervention utilisateur. Risque externe non modifiable par le workflow.

6. Ecarts et resolutions¶

Gate 3 (CONFORMITY_CHECK)¶

Gate 5 (AMBIGUITY)¶

Gate 8 (CLOSURE)¶

7. Risques identifies¶

8. Capitalisation¶

Patterns confirmes (deja vus dans d'autres stories)¶

1. Stubs inter-PD avec story destination (PD-250, PD-251) : Documenter // Statut : En cours — PD-251 dans les sections pertinentes attenue la criticite en Gate 8 de MAJEUR a MINEUR. ROI confirme : 0 ecart MAJEUR en Gate 8 sur les 2 stubs PD-251.

2. Specifications documentaires avec criteres qualitatifs non quantifies (PD-244) : Les invariants sur la "maintenabilite" (Mermaid) et la "non-duplication" (verbatim) necessitent un seuil chiffre des la specification. Sans seuil, Gate 3 RESERVE systematique car le critere est subjectif.

3. correction directe Claude en Gate 5 pour les ecarts DIV du plan (PD-250, PD-251) : Claude corrige le plan et les code contracts sans passer par ChatGPT — convergence rapide (delta +1.125 en un passage).

Nouveaux patterns identifies¶

1. Validation structurelle comme substitut a mkdocs build : Pour les projets documentaires, la validation structurelle (markdownlint 0 erreur + YAML navigation syntaxiquement valide + tous les fichiers references existent sur disque + coherence inter-chapitres) constitue un substitut acceptable a mkdocs build effectif. Score Gate 8 : 9.81/10 avec ce seul substitute. A documenter comme "niveau de validation documentaire minimum acceptable" dans les templates.

2. Decomposition par niveaux pour projets documentaires (Niveau 0 parallele, Niveau 1 sequentiel, Niveau 2 integration) : L'architecture 3 niveaux avec bloc cache-first identique pour les 10 agents paralleles produit une homogeneite de style inter-chapitres sans need de phase de revision editoriale post-production. Le glossaire en Niveau 1 peut lire tous les chapitres et deduplique automatiquement les termes.

3. Gate 8 GO v1 sur projet documentaire : Premier precedent dans le domaine legal-compliance. Les conditions ayant permis ce resultat : (a) 0 markdownlint error, (b) 12/12 CC PASS documentaires, © stubs documentes avec story destination, (d) 1 seule correction de fond (ECT-02 formule ch08). Ces conditions sont reproductibles.

4. Review ChatGPT insuffisante sur projets documentaires : ChatGPT via OpenCode ne consulte pas les chapitres du manuel lors de la revue d'acceptabilite (28 lignes, 0 verification INV/CC). Le rapport d'acceptabilite Claude doit etre suffisamment detaille pour compenser. Signal de risque pour les prochains projets documentaires : pre-voir que la review ChatGPT sera superficielle et que la Gate 8 reposera principalement sur l'acceptabilite Claude.

9. Recommandations¶

1. Ajouter une contrainte markdownlint dans les code contracts documentaires : Chaque contrat de chapitre doit inclure max_line_length: 80 (texte narratif) avec note d'exemption pour les tableaux et blocs de code. Evite les 419 erreurs post-implementation et le recours a un script de correction automatise.

2. Creer un template de revue d'acceptabilite specifique aux projets documentaires : La revue ChatGPT Phase 1 doit verifier au minimum : (a) 1 invariant par invariant de la spec, (b) 1 code contract par contrat, © coherence inter-chapitres sur 2-3 references croisees. Un template avec checklist imposerait ce minimum.

3. Verifier gitignore avant de designer un repertoire cible en etape 4 : La phase Go/No-Go (etape 4) doit inclure une verification explicite : "Le repertoire cible {path} est-il tracke par git ?" — si non, choisir un autre emplacement ou modifier .gitignore. Pour ProbatioVault-doc : utiliser docs/sae-manual/ plutot que _build/docs/sae-manual/.

4. Documenter le substitut mkdocs build dans le plan : Si mkdocs n'est pas disponible localement, le plan doit declarer explicitement "Validation par verification structurelle : markdownlint + YAML nav + existence fichiers" comme critere de validation d'INV-249-10, pour que la Gate 8 ne signal pas l'absence de build comme ecart.

5. Injecter les learnings de PD-244 dans les prochaines stories documentaires : Les patterns de PD-244 (criteres qualitatifs a quantifier, anti-verbatim, modele d'etats documentaire) sont directement applicables aux stories documentaires futures (politiques d'archivage, PAE, documentation certification). Tagguer #documentaire #legal-compliance dans learnings.jsonl.

10. Ameliorations process¶

10.1 Amelioration haute priorite — Contrainte markdownlint dans les code contracts¶

Fichier cible : templates/prompts/6a-decomposition.md (template de decomposition documentaire)

Modification : Ajouter dans la section "Regles transversales de redaction" une regle explicite :

### Contrainte markdownlint (OBLIGATOIRE)

Chaque ligne de texte narratif DOIT faire <= 80 caracteres.
EXEMPTION : les lignes de tableaux Markdown, les blocs de code (``` ... ```),
les URLs et les ancres de section sont exempts de cette limite.

Raison : les agents de niveau 0 produisant en masse des lignes longues genere
des centaines d'erreurs markdownlint post-implementation (PD-249 : 419 erreurs).

Priorite : haute

10.2 Amelioration haute priorite — Template de revue d'acceptabilite documentaire¶

Fichier cible : templates/prompts/7a-review-code.md (ou nouveau fichier 7a-review-doc.md)

Modification : Creer une variante du prompt de revue Phase 1 pour les projets documentaires, incluant une checklist minimum :

## Checklist revue documentaire (OBLIGATOIRE)

Pour chaque invariant de la specification :
- [ ] INV-{N} : {description} — verifier sur le(s) chapitre(s) concernes

Pour chaque code contract :
- [ ] CC-{N} : sections presentes ? diagrammes presents ?

Coherence inter-chapitres :
- [ ] Verifier 2-3 references croisees (ex : statut PD-251 coherent entre ch06 et ch07)

Priorite : haute

10.3 Amelioration moyenne priorite — Verification gitignore en phase Go/No-Go¶

Fichier cible : CLAUDE.md (section "Etape 4 — Checklist pre-soumission Gate 5", sous-section "Phase 0 — Go/No-Go")

Modification : Ajouter une hypothese critique dans le tableau Go/No-Go :

Priorite : moyenne

Note : Cette modification touche CLAUDE.md — validation humaine requise avant application.

10.4 Amelioration moyenne priorite — Documenter le substitut mkdocs build¶

Fichier cible : templates/outputs/PD-XX-plan.md (section "Contraintes techniques" — Framework documentaire)

Modification : Ajouter un bloc conditionnel :

### Validation MkDocs (si mkdocs non disponible localement)

Si `mkdocs build` n'est pas executable localement, la validation d'INV-{N}-10
se fait par verification structurelle :

1. `markdownlint docs/sae-manual/*.md` — 0 erreur requise
2. Validation YAML de `mkdocs.yml` : tous les fichiers references existent
3. Coherence inter-chapitres : 0 reference croisee cassee

Ce substitut est declare "validation structurelle suffisante" et doit etre
documente dans le plan comme choix explicite.

Priorite : moyenne

10.5 Amelioration basse priorite — Invariant-candidat pour les projets documentaires¶

Fichier cible : data/learnings.jsonl (archive uniquement)

Learning a ajouter :

{
  "story": "PD-249",
  "gate": "rex",
  "verdict": "GO",
  "tags": ["#documentaire", "#markdownlint", "#invariant-candidate", "#legal-compliance"],
  "learning": "[Projets documentaires] INV candidat : INV-DOC-MARKDOWNLINT — Toute ligne de texte narratif <= 80 chars (exemption : tableaux, code blocks, URLs). Sans cette contrainte dans les code contracts, les agents niveau 0 produisent en masse des lignes longues -> correction post-implementation couteuse (PD-249 : 419 erreurs).",
  "date": "2026-02-27"
}

Priorite : basse