building-preaction-report

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 :

1. Comprehension de la demande (depuis request.json)
2. Exemples de code DIVA similaires (depuis evidence.confirmed + evidence.new_findings)
3. Fonctions du langage DIVA utiles (deduites des snippets + catalogue statique)
4. Etude d'impact (depuis evidence.impact.callers)
5. Endroit ou agir (propositions generees par le LLM au CP5 -- le template reserve la section)
6. Pistes de recherche complementaires (suggestions contextuelles)
7. 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) :

1. Borne dure : max 5 exemples section 2, max 12 fonctions section 3, max 15 appelants section 4.1
2. Marquage : toute occurrence de [X.12] doit etre accompagnee d'un statut CONFIRME / DISPARU / NOUVEAU si la phase 3 a tourne
3. Chemin absolu : toute reference fichier:ligne est un chemin absolu (sinon le rapport est rejete)
4. En-tete complete : type / domaine / confiance / couverture Neo4j obligatoires
5. 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 :

1. ReportContext nominal (donnees completes)
2. ReportContext pathologique (enclosing_block=None, targeted_symbol="", file="", etc.)
3. 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 guillemets
• TestValidatorExtended (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