DELTA37/structured-report

Rapport structuré

Un fichier HTML autonome (sans réseau) qui permet à un lecteur occupé de :

1. voir l'ensemble du travail sous forme de carte des tâches, avec ce qui l'attend dans chaque tâche,
2. ouvrir n'importe quelle tâche — et n'importe quelle étape à l'intérieur — et auditer comment elle a été réalisée et pourquoi chaque affirmation est considérée comme vraie,
3. répondre aux questions de l'agent directement dans le rapport, et voir quels prompts ont produit quoi.

Structure vs contenu

• La structure appartient au modèle (assets/template.html) : mise en page, noms des sections (Problème, Tâche, Contexte, Conclusions, Hypothèses, Résultat, Non vérifié, Workflow, Nécessite approbation, Vos actions), leur ordre, les statuts, les icônes et les libellés de l'interface. Fixe, toujours en anglais. Les icônes marquent uniquement la structure, jamais le contenu.
• Le contenu est le vôtre : le JSON, dans la langue de l'utilisateur. scripts/build.py le valide et remplit les espaces réservés du modèle. Vous n'écrivez jamais de HTML et n'inventez jamais de sections.

Workflow

1. Collectez le matériel : messages, résultats d'outils, fichiers, commandes, liens, tests, mesures, décisions. Signalez uniquement ce qui s'est réellement passé.
2. Divisez-le en tâches (1–12) : une tâche = un objectif avec son propre résultat. Reliez-les avec des links : depends, blocks, related.
3. Remplissez chaque tâche en suivant les règles ci-dessous et references/schema.md.
4. Écrivez le JSON — par défaut reports/<YYYY-MM-DD>-<slug>.json dans le répertoire de travail.
5. Construisez : python3 <skill>/scripts/build.py <fichier>.json → <fichier>.html. Corrigez chaque error: ; lisez chaque warning: et corrigez-le sauf s'il est vraiment vrai.
6. Ouvrez-le localement (open / xdg-open / start) et donnez le chemin. Ne le téléchargez jamais.
7. Dans le chat : 2–4 lignes — le résultat principal et ce qui attend le lecteur.

Rapport vivant : suivez la session, récupérez les réponses

Lorsque l'utilisateur souhaite que le rapport reste à jour pendant la session (ou demande un rapport suivi / vivant), liez la session une fois :

python3 <skill>/scripts/track.py start reports/<fichier>.json      # crée <fichier>.journal.json

Ensuite, le hook UserPromptSubmit (à installer une fois : track.py install-hook, qui ajoute également le hook Stop) enregistre chaque prompt utilisateur dans le journal et vous rappelle le numéro du prompt. Après chaque prompt qui modifie le travail, mettez à jour le JSON et reconstruisez — build.py génère une empreinte de chaque bloc (chaque nœud × section) et marque les blocs nouveaux ou modifiés avec le prompt actuel. N'écrivez jamais de marqueurs vous-même. Le rapport affiche un rail Prompts ; en cliquant sur un prompt, on surligne ce qui est apparu (vert) ou a changé (bleu).

Questions pour le lecteur. Placez les décisions dans approvals. Chacune est une question avec des options — exclusives par défaut (une seule réponse) ou "multi": true (toute réponse applicable) — votre recommend (une liste pour multi), why et due. Le lecteur a toujours « votre propre réponse » comme option supplémentaire ; une question sans options reçoit une réponse en texte libre. Dans le rapport, les questions ouvertes d'une section Nécessite approbation forment une série, une question à la fois : une option exclusive répond et passe à la suivante, une option multiple ou une réponse personnelle est confirmée avec Suivant, la série se termine par une revue de toutes les réponses, et Soumettre les réponses vous les envoie — il n'y a pas d'autre moyen d'envoyer, et les actions (étapes que le lecteur effectue) n'ont pas de champs de saisie. Les réponses vont à un service de réponses local (127.0.0.1:47319, démarré et maintenu à jour par la construction) même lorsque le rapport est ouvert comme un simple fichier, et sont stockées dans le journal comme le prompt suivant. Tant que le rapport contient des questions ouvertes, maintenez un écouteur en arrière-plan avec une commande background :

python3 <skill>/scripts/track.py wait reports/<fichier>.json

Lorsque le lecteur envoie, wait affiche les réponses et se termine — cette sortie vous revient : traitez-la exactement comme le prompt de l'utilisateur et continuez ; redémarrez wait s'il reste des questions. Si aucun écouteur n'est actif, le hook Stop remet les réponses en file d'attente avant la fin de votre tour, et le hook UserPromptSubmit les attache au message suivant de l'utilisateur — les réponses ne sont jamais perdues. Les questions auxquelles il a été répondu s'affichent comme répondues après la prochaine construction. --static construit un rapport sans canal de réponse (pour le partage en dehors de cette machine) : les questions sont affichées en lecture seule, sans champs de saisie.

Lien sous la zone de saisie. scripts/statusline.py affiche une ligne d'état pour le rapport de la session — son titre sous forme de lien cliquable qui ouvre le HTML dans le navigateur, et le nombre de questions en attente. Utilisez-le comme ligne d'état ou ajoutez sa sortie à une ligne existante ; il n'affiche rien pour les sessions sans rapport.

Chaque bloc du rapport comporte un bouton Copier en Markdown (l'ensemble du rapport, une carte de tâche, un rapport, une section, un élément unique, une étape, un prompt) — indiquez au lecteur de l'utiliser lorsqu'il souhaite coller quelque chose ailleurs.

Les règles qui rendent le rapport fiable

Séparez ce que vous savez de chaque chose ; ne brouillez jamais les frontières.

• contexte — sources que vous avez effectivement consultées : id (C1…), title court, une url réelle, et une note avec le fait exact extrait. N'inventez jamais d'URL. Privilégiez les URL de dépôt / web : les liens file:// ne s'ouvrent pas sur la machine du lecteur (build émet un avertissement ; un fichier local manquant est une erreur).
• inférences — conclusions, chacune avec basis (ids de contexte) et confidence. Pas de basis → c'est une hypothèse.
• hypothèses — considérées comme vraies sans vérification : why, comment verify, risk si faux.
• non vérifié — ce que vous n'avez pas vérifié ou fait, avec why. Les lecteurs se fient à cela plus qu'à toute autre chose ; dites-le clairement. Une tâche terminée sans unchecked reçoit un avertissement ([] signifie « tout vérifié » — uniquement si c'est vrai).
• résultat — ce qui existe maintenant, sous forme d'éléments typés. Chaque élément verified nécessite how : la commande, le test ou le lien qui le prouve — la construction échoue sans cela.
• étapes — les étapes que vous avez réellement suivies, 2–8 par niveau. Une étape est le même type de nœud qu'une tâche : id + title obligatoires, tout champ de tâche autorisé, ses propres stages + flow, à n'importe quelle profondeur. Sur la carte, elle affiche detail (ce que vous avez fait), outcome (ce qui est ressorti), status, when, uses. Cliquer sur une étape ouvre son rapport dans la même structure, donc donnez un contenu réel aux étapes qui ont effectivement constitué un travail. Les impasses sont aussi des étapes (failed / skipped).
• prochaines étapes sont des étapes planifiées — tout ce qui reste à faire est une étape avec status: "planned", un detail (ce qui sera fait) et when (la condition ou le moment : « après votre approbation », « lundi »). Une tâche non terminée sans étape planifiée ou en cours reçoit un avertissement.
• approbations — décisions que seul le lecteur peut prendre : la question, why elle lui revient, options (exclusives, ou multi: true), votre recommend (une des options ; une liste pour multi), due. Plusieurs questions liées dans un même nœud deviennent une série — ordonnez-les selon l'ordre dans lequel le lecteur doit y répondre. Ne demandez jamais d'approbation pour quelque chose déjà fait.
• actions — choses que seul le lecteur peut faire, avec la command exacte et due le cas échéant.
• secrets — le rapport est susceptible d'être transmis. La construction échoue sur tout ce qui ressemble à une clé, un jeton, une clé privée, un JWT, une affectation de mot de passe ou des identifiants dans une URL (gitleaks est également utilisé s'il est installé). Supprimez-le du contenu ; ne le « masquez » jamais manuellement. Les secrets dans les prompts enregistrés sont masqués automatiquement.

Écrivez la structure, pas de la prose

Chaque champ de texte rend la structure, donnez-lui donc une structure :

• - item → puces ; 1. item → numéroté (uniquement pour les séquences réelles) ; deux lignes ou plus de Clé: valeur → un tableau aligné ; un tableau JSON de chaînes → des puces.
• **gras** pour les une ou deux choses par ligne que le lecteur ne doit pas manquer ; ==texte== pour surligner ; `code` pour les identifiants, chemins, commandes.
• Pas de paragraphe de plus de deux phrases ; pas de sous-titres ni de lignes d'introduction.

Indications pour les champs : brief — 1–3 lignes Clé: valeur pour la carte. problem — faits clé/valeur. goal — puces de ce que signifie « fait ». result.summary — clé/valeur ou puces.

Langue

Contenu dans la langue de l'utilisateur, meta.lang défini sur son code. Les libellés de structure restent en anglais.

Fichiers

• assets/template.html — la structure : balisage avec espaces réservés, styles, icônes et un script pour la mise en page, la navigation, la recherche, le rail de prompts et la réponse.
• scripts/build.py — valide le contenu (vérifications ci-dessus, secrets), marque le journal, rend le modèle. --check valide uniquement ; --template utilise un autre modèle.
• scripts/track.py — start, wait, hook, stop-hook, daemon, status, install-hook (voir sa docstring).
• scripts/statusline.py — le lien du rapport pour la ligne d'état de Claude Code.
• references/schema.md — tous les champs.
• examples/ — exemples en anglais et en russe ; l'exemple russe contient un journal de 5 prompts.