TEMPLATE — Story diagnostique scientifique¶
Patron réutilisable pour une Story de diagnostic (mirror s41/s42/s43). Mandaté par ADR-0095. Référence canonique : CVN-N001-EI-S05 (hub). Copier la structure, pas le contenu. Chaque Story diagnostique produit 5 artefacts (hub + plan + archi + runbook + test strategy) sur docs.cvntrade.eu (SSoT, ADR-77), liés depuis le hub Epic + OpenProject (ADR-76).
Composition (ADR-0101) : ce patron compose le template universel
TEMPLATE_story_doc_canonical.md— la structure documentaire (les 5 artefacts + les chapitres problématisation→DoD→Consolidation) en vient ; ce fichier n'ajoute que les add-ons méthodologiques diagnostiques (decision-table pré-enregistrée, envelope bootstrap, contrôle multiple-testing). Ne pas dupliquer l'universel.
Les 5 artefacts (emplacements canoniques)¶
| Artefact | Emplacement | Rôle |
|---|---|---|
| Hub Story | stories/<cvn_id>/index.md |
portail : lie les 4 autres + état + traçabilité |
| Plan dossier | reviews/<date>-<cvn_id>-<slug>-plan.md |
quoi & pourquoi (→ committee plan_review) |
| Architecture | design/<cvn_id>-<slug>-architecture.md |
comment c'est construit (Hamilton-native) |
| Runbook | runbooks/runbook_diagnostic_<snn>_<slug>.md |
comment l'opérateur s'en sert |
| Test strategy | stories/<cvn_id>/test_strategy.md |
comment on le valide |
Squelette du PLAN dossier¶
Chapitres narratifs (amont) — valorisent + rendent accessible : 1. Problématisation (langage non-technique, ~2 p.) : la question en une phrase, pourquoi maintenant, les pièges/illusions, ce qu'on mesure vraiment, l'honnêteté du verdict, pourquoi ça compte (la décision que ça alimente). 2. User stories (« En tant que… je veux… afin de… ») mappées aux sections. 3. Hypotheses (EN) : chaque hypothèse posée + énoncé NULL testé + méthode de test. Distinguer hypothèses testées vs working assumptions surfacées. 4. State of the art (EN, références) : théorie + best practices qui fondent la méthode, mappées aux hypothèses. 5. Consolidation & traçabilité : matrice problème→hypothèse→US→section→littérature (aucun fil ne dangle) + decision routing (verdict → action).
Sections techniques (§0-§7) — spec implémentable : - §0 provenance · §1 objectif + règles de décision pré-enregistrées (pseudo-code verdict, tie-break, seuils) · §2 scope · §3 approche (Hamilton-native, UQ) · §4 fichiers · §5 risques · §6 success criteria + ops · §7 décisions tranchées.
Invariants méthodologiques (à ne pas négocier)¶
- Pré-enregistrement : la règle de décision (verdict + seuils + tie-break + priorités) est figée avant le run (anti data-snooping ; Nosek 2018). Toute valeur décisionnelle est dans le plan, jamais inventée au test (sinon divergence plan↔test).
- Statistique d'enveloppe bootstrappée quand on balaie un paramètre (anti biais de sélection / winner's curse ; White 2000, Hansen 2005) — bootstrapper
max, jamais l'argmax-point. - Correction multi-comparaisons (Bonferroni / FWER) sur les tests décisionnels.
- Décision keyée sur la SIGNIFIANCE (position de l'IC), jamais sur le point-estimate (leçon S05 r2.7 : un point>0 non-significatif ≠ effet).
- Inconclusifs first-class :
INCONCLUSIVE_UNDERPOWERED/_COST_SENSITIVE/_TOOLINGsont des verdicts honnêtes, pas des échecs (« on ne sait pas » assumé). - No-crash / fail-loud (ADR-25) : tout chemin d'erreur → verdict
INCONCLUSIVE_TOOLINGstructuré, jamais unraiseà l'UI. Pas de NaN propagé. Pas deprint(ADR-31). - Gate des entrées non-mesurées : toute valeur qui décide (coûts réels, etc.) gate le full run tant qu'elle n'est pas mesurée — placeholders OK pour le smoke (câblage), pas pour le verdict.
Squelette ARCHITECTURE¶
Style Hamilton-native 2-couches (Airflow orchestration / Hamilton compute pur / I/O isolée / décision en fonctions pures) ; graphe de nodes nommé (pas de monolithe, [[feedback_hamilton_native_no_wrappers]]) ; contrats d'interface (output schema) ; points d'intégration ; catalogue d'événements Loki ; conformité ADR.
Squelette RUNBOOK¶
Quoi & quand · prérequis (table, « si KO ») · déclenchement (DAG + param JSON) · catalogue des verdicts + désambiguïsation · lire la sortie + reason codes + decision routing · observabilité Loki · troubleshooting (incl. échec partiel de pods) · réplication.
Squelette TEST STRATEGY¶
Pyramide + tiers ADR-83 · table de décision exhaustive (toutes les branches AVANT le code — c'est là qu'on attrape les trous logiques sur papier) · test d'exhaustivité (produit cartésien → exactement-un-verdict, pas la couverture-de-branche qui rate les fall-through) · invariants (déterminisme bit-identical, no-crash, anti look-ahead) · 3 niveaux (unit / smoke / full gated) · mapping tests↔hypothèses↔US · validation système (le verdict réel n'est PAS un test CI).
Scaffold¶
/diagnostic-scaffold génère le squelette 2-couches + invariants bakés (no-crash, path-guard, ADR-92, capture-spy). Les _probe_* + _decide_* partent en stubs NotImplementedError → hand-author depuis la spec pré-enregistrée du plan.