| name | building-preaction-report |
| description | Assemble un rapport d'analyse pre-action a partir des 3 JSON intermediaires (request, candidates_x12, evidence_x13). Modele catalogue-driven : evalue 9 types de contenus par pertinence (via `content_types.py`), amorce deterministement la matiere de chaque type retenu (propositions, grep commands, table Ce4, ...), assemble les fragments Jinja correspondants. Produit un markdown et un JSON de metriques avec tracabilite `types_included`. Applique les regles de marquage X.12/X.13 systematique et les criteres de qualite pre-action. A utiliser quand les 3 JSON (request, candidates, evidence) sont disponibles et qu'il faut produire le rapport markdown final destine au developpeur.
|
Building Pre-Action Report
Contenu
- Utilisation rapide
- Parametres d'entree
- Livrables
- Structure du rapport (7 sections)
- Metriques JSON parallele
- Regles de qualite
- Scripts disponibles
- References
Utilisation rapide
py .claude/skills/building-preaction-report/scripts/build_report.py \
--request output/request.json \
--candidates output/candidates_x12.json \
--evidence output/evidence_x13.json \
--output-dir output
Le script calcule automatiquement le slug (40 car max, ASCII-lowercase) depuis request.titre et la date (YYYYMMDD locale). Les 2 livrables sont ecrits dans --output-dir.
Parametres d'entree
| Parametre | Format | Obligatoire | Defaut |
|---|
--request | Chemin request.json (phase 1) | Oui | -- |
--candidates | Chemin candidates_x12.json (phase 2) | Oui | -- |
--evidence | Chemin evidence_x13.json (phase 3) | Oui | -- |
--output-dir | Repertoire de sortie | Non | output/ |
--slug | Slug manuel (override auto) | Non | auto depuis request.titre |
--date | Date YYYYMMDD (override) | Non | date du jour |
Livrables
Rapport markdown
output/preaction-<slug>-<YYYYMMDD>.md
Encodage : UTF-8 + LF (livrable humain, pas source DIVA). Structure detaillee dans reference/report-sections.md.
JSON de metriques
output/preaction-<slug>-<YYYYMMDD>.json
Metriques pour evaluation : nb_exemples, nb_fonctions, nb_impacts, confiance_globale, couverture_neo4j, duree_seconds_total.
Structure du rapport (7 sections)
Structure canonique : 7 sections + annexe (detail dans reference/report-sections.md). En resume :
- Comprehension de la demande (depuis request.json)
- Exemples de code DIVA similaires (depuis evidence.confirmed + evidence.new_findings)
- Fonctions du langage DIVA utiles (deduites des snippets + catalogue statique)
- Etude d'impact (depuis evidence.impact.callers)
- Endroit ou agir (propositions generees par le LLM au CP5 -- le template reserve la section)
- Pistes de recherche complementaires (suggestions contextuelles)
- Points d'attention (surcharges, conventions, disclaimers)
Plus l'annexe "Sources consultees" avec les stats de collecte.
Metriques JSON parallele
Schema : voir reference/report-sections.md section "JSON de metriques".
Champs cles :
| Metrique | Calcul |
|---|
exemples_similaires | len(evidence.confirmed) + len(evidence.new_findings) |
fonctions_utiles | Comptage des fonctions extraites des snippets (heuristique) |
appelants_potentiels | len(evidence.impact.callers) |
disclaimers_x12 | Comptage des marqueurs [X.12] dans le rapport |
confirmed_x13 / disappeared_x13 / new_x13 | Comptage des statuts |
confiance_globale | forte si >=3 confirmed et >=5 functions, moyenne si >=1 confirmed, faible sinon |
couverture_neo4j | disponible / partielle / absente (selon evidence.scope.neo4j_status_upstream) |
Regles de qualite
Appliquees par le script (validation post-render) :
- Borne dure : max 5 exemples section 2, max 12 fonctions section 3, max 15 appelants section 4.1
- Marquage : toute occurrence de
[X.12] doit etre accompagnee d'un statut CONFIRME / DISPARU / NOUVEAU si la phase 3 a tourne
- Chemin absolu : toute reference
fichier:ligne est un chemin absolu (sinon le rapport est rejete)
- En-tete complete : type / domaine / confiance / couverture Neo4j obligatoires
- Confiance degradee : si moins de 3 exemples confirmes,
confiance_globale = faible et un encadre explique les ecarts
Voir reference/report-sections.md pour le detail par section.
Conventions de templating (RETEX 2026-04-18 -- "correct du premier coup")
Le renderer Markdown/Mermaid de Claude Desktop est un sous-ensemble restreint. Les fragments Jinja2 doivent respecter :
Markdown
- Jamais d'italique
_..._ autour d'un paragraphe contenant <...> en inline code -- le renderer casse l'italique en voyant <champ> comme balise HTML inconnue. Utiliser blockquote + bold label : > **Attendu :** texte avec \ENT.$champ`...`.
- Placeholders textuels : preferer
$foo, {foo} ou FOO aux <foo>. Les angle brackets hors code block sont interpretes comme HTML.
- Italique simple (sans code ni placeholders) : OK, ex.
_Pas de constantes nommees._.
- Features fiables :
#, **bold**, `code`, tables, [lien](url), > quote, <details><summary>, listes ordonnees/non-ordonnees.
Mermaid
- Seul
<br/> est garanti dans les labels de noeuds. Ne pas utiliser <code>, <em>, <span>, <strong> -- ils s'affichent en dur.
- Stadium : utiliser
N(["label"]), pas N@{shape: stadium, label: "..."} (syntaxe nouvelle pas toujours supportee).
- Quotes dans labels : les supprimer ou utiliser
#quot; (pas ", pas toujours decode).
- Labels courts : idealement < 50 caracteres. Si plus long, deporter l'info dans une liste "Ouvrir les fichiers" apres le diagramme.
Contenu (anti-stub)
- Jamais de phrase commencant par un pronom relatif (
qui, que, dont, ou) apres un label de bullet. Si l'extraction automatique ne reconstitue pas un enonce complet, ne pas generer la ligne -- meilleure omission que stub.
- Jamais de placeholder generique inutile (
(cf. ticket d'origine), a completer, TODO). Le validator validate_report() les detecte.
- Anomalie section : produire 3 elements structures (contexte declencheur / etat observe / etat attendu) ou echouer et laisser le LLM completer au CP5.
Test battery obligatoire avant merge
Chaque fragment .md.j2 doit avoir un golden test avec :
- ReportContext nominal (donnees completes)
- ReportContext pathologique (
enclosing_block=None, targeted_symbol="", file="", etc.)
- Assertion : le rendu passe
validate_report() sans error.
Emplacement : scripts/tests/test_fragments.py + tests/golden/*.md.
Rationale : les bugs B10 (Mermaid <code>), B11 (Mermaid stadium), B12 (italique+angle brackets) ont couté 2h d'iteration le 2026-04-18. Un test golden les aurait attrapes hors-ligne.
Scripts disponibles
scripts/build_report.py
scripts/content_types.py
scripts/templates/report.md.j2 # Squelette
scripts/templates/fragments/*.md.j2 # Fragments par type de contenu
scripts/tests/test_fragments.py # Tests unitaires (golden + validator)
Dependance : Jinja2 3.1+ (prerequis commun du workspace, voir .claude/skills/README.md).
Lancer les tests
cd .claude/skills/building-preaction-report/scripts
py -m unittest tests.test_fragments -v
Couverture actuelle (19 tests) :
TestChainOfBlame (6 tests) : cas nominal, action sans ligne, fn_noline, available=false, liens file://, gestion des guillemetsTestValidatorExtended (13 tests) : detection et non-detection des patterns interdits (fragments de phrase, italique+angle brackets, stubs, HTML Mermaid) + verification du rapport final publie
Avant toute modification d'un fragment .md.j2 : lancer les tests, modifier, relancer. Un fragment qui casse un test ne part pas en production.
References
reference/report-sections.md -- detail des 7 sections, metriques, critere de qualite
