Générateur de rapports

Le propriétaire décrit un rapport une fois. Vous le construisez, l'exécutez et enregistrez la définition pour qu'il ne soit plus jamais décrit.

Les propriétaires extraient les chiffres de trois tableaux de bord à la main et tentent de trouver l'histoire par eux-mêmes. L'objectif est d'y mettre fin.

Étape 1 — Vérifier l'existence d'une définition

Avant toute chose, lisez reference/saved_reports.md et vérifiez si ce rapport existe déjà. Vérifiez aussi la présence d'un fichier report-definitions.md dans le répertoire de travail — c'est là que les définitions s'enregistrent quand le dossier skill n'est pas accessible en écriture (voir étape 7).

Si le propriétaire dit « le même rapport qu'la dernière fois », « lance celui hebdomadaire » ou nomme un rapport pour lequel vous avez une définition, allez directement à l'étape 4 et exécutez-le. Ré-interroger quelqu'un sur un rapport qu'il a déjà défini est le meilleur moyen de rendre ce skill cassé.

Si rien ne correspond, continuez.

Étape 2 — Transformer la description en spécification

Les propriétaires décrivent les rapports vaguement : « chaque lundi, ventes par localisation versus l'année dernière, AR vieillissement et pourcentage de main-d'œuvre ». Cette phrase contient quatre décisions distinctes. Résolvez-les en une spécification au format de reference/report_spec.md :

• Métriques — chacune nommée, avec sa formule et sa source
• Regroupement — par localisation, produit, client, canal, représentant
• Comparaison — versus période antérieure, versus l'année dernière, versus cible
• Période — la fenêtre que chaque exécution couvre
• Cadence — ponctuel, hebdomadaire, mensuel, trimestriel

Déduisez ce que vous pouvez raisonnablement. « Ventes par localisation vs l'année dernière » vous donne la métrique, le regroupement et la comparaison — ne posez pas de questions à ce sujet. Posez des questions uniquement sur ce qui est réellement ambigu, et regroupez-les plutôt que de poser une question à la fois.

Les deux questions qui valent presque toujours la peine d'être posées :

• Quelle période chaque exécution couvre-t-elle — mois calendaire, 30 derniers jours, mois à ce jour ?
• Un nombre comme « pourcentage de main-d'œuvre » est-il mesuré par rapport au chiffre d'affaires ou aux coûts totaux ?

Se tromper sur ces points produit un rapport qui semble correct mais est secrètement faux, ce qui est pire que de demander.

Étape 3 — Confirmer la spécification, une seule fois

Montrez la spécification résolue dans un bloc compact. Demandez une confirmation unique, puis construisez. Ne passez pas en revue la spécification champ par champ avec le propriétaire — il l'a décrite en une phrase et s'attend à une réponse unique.

S'il corrige quelque chose, appliquez-le et continuez. Ne confirmez pas une deuxième fois.

Étape 4 — Extraire les données

Lancez chaque appel source en un seul lot parallèle. Consultez reference/data_sources.md pour le mappage métrique-outil.

Sources, essayées simultanément :

• Le grand livre — MYOB, NetSuite, QuickBooks, Xero ou Zoho Books, selon la connexion ; homologues par ../../shared/connector-neutrality.md. Lignes de compte de résultat, chiffre d'affaires, dépenses, vieillissement AR, AP, répartition par classe et localisation. MYOB ne couvre que compte de résultat, AR et comptes créditeurs, trois exercices financiers en arrière. Si deux grands livres sont connectés, demandez lequel est la source de confiance et prenez les totaux de celui-là
• HubSpot — deals, étapes, propriétaires, dates de clôture, valeur du pipeline
• PayPal, Square, Stripe — règlements, frais, remboursements, détail des transactions
• Shopify — commandes, chiffre d'affaires au niveau SKU, statut d'exécution
• Ramp, Expensify — dépenses de carte et détail des dépenses. Les deux sont des sources de lecture ici ; Expensify est en lecture seule

Si une source génère une erreur ou ne retourne rien, enregistrez-le et continuez. Ne bloquez jamais le rapport entier sur un seul connecteur défaillant.

L'absence totale de connecteurs est un chemin supporté, pas un échec. Demandez un export CSV ou XLSX, lisez-le et construisez le rapport identique à partir du fichier. Dites-le clairement : « Je ne vois pas de source de données connectée. Exportez le rapport de ventes de votre système et déposez-le ici — je construirai le même rapport à partir de ce fichier. » Les propriétaires avec un écosystème d'outils étendu vivent dans ce mode, et le rapport est tout aussi bon.

Étape 5 — Calculer et vérifier la cohérence

Calculez chaque métrique nommée dans la spécification. Puis vérifiez les résultats avant de les présenter. Lisez reference/gotchas.md pour les modes de défaillance qui se produisent réellement.

Les vérifications qui détectent les vraies erreurs :

• Limites de période. Un mois courant partiel comparé à un mois antérieur complet paraît toujours une effondrement. Comparez des périodes identiques ou labélisez explicitement la période partielle.
• Double comptage. Une commande Shopify et son règlement Stripe constituent une vente. Si les deux sources sont connectées, choisissez-en une comme source de chiffre d'affaires et notez laquelle.
• Groupes vides. Une localisation sans ventes cette période doit apparaître avec un zéro, pas disparaître. Une ligne disparue ressemble à un problème de données.
• Totaux qui ne correspondent pas. Si les lignes regroupées ne font pas la somme du total, dites-le plutôt que de publier un nombre dont vous ne pouvez pas vous porter garant.

Étape 6 — Livrer

Deux artefacts, toujours, dans cet ordre.

Le résumé chat vient en premier. Suivez reference/output_template.md. Commencez par ce qui a changé et ce que cela signifie, pas un dump de tableau. Le propriétaire a demandé un rapport parce qu'il veut une décision, pas une feuille de calcul.

Règles d'écriture, identiques à chaque skill de rapports dans ce plugin :

• Les nombres en premier, les mots après. Pas « les ventes étaient fortes » — « USD 43 200, en hausse de 8 % versus l'année dernière. »
• Chaque nombre porte sa comparaison. Un chiffre sans référence est une perspective manquée.
• Nommez le point aberrant. « Portland baisse de 22 %, la seule localisation sous l'année dernière » vaut mieux que « les résultats sont mitigés. »
• Trois constats maximum dans le résumé. Le classeur contient tout le reste.

Puis l'XLSX. Un onglet par groupe de métriques, un onglet de synthèse en premier, données brutes extraites sur un onglet final pour que le propriétaire puisse vérifier vos calculs. Construisez-le avec un script plutôt qu'à la main.

Puis la page rapport, selon la préférence de sortie enregistrée du propriétaire — ne prédéfinissez jamais un fichier markdown. Vérifiez le bloc ## Business context pour la préférence Output preference (règle de guide de style partagée, ../../shared/artifact-style.md) :

• Artefact visuel (par défaut) : rendez le rapport comme une page HTML au style maison — chaque métrique principale est une tuile stat avec sa comparaison comme ligne de contexte ; les lignes regroupées (par localisation, produit, représentant) sont un tableau avec des nombres tabulaires alignés à droite ; toute métrique versus cible porte une pilule de statut (bon sur cible, avertir glissement, critique manqué) ; les trois constats ouvrent la page dans leur propre panneau ; les sources « n/a » figurent dans une ligne de pied de page discrète. Additif au résumé chat et au classeur, jamais un remplacement.
• Préférence docx / md / notion / canva : livrez le même contenu dans cette forme — un fichier DOCX ou markdown, une page Notion créée via le connecteur (destination nommée, jamais écrasant), ou un Doc Canva créé via le connecteur Canva (un nouveau design chaque exécution, nommé avec la date ; les tableaux deviennent des listes) ; revenez à l'artefact visuel si Notion ou Canva ne sont pas connectés — et dites-le. L'XLSX s'ajoute toujours.
• Meilleur pour le skill : utilisez l'artefact visuel — un rapport se lit à l'écran et se compare semaine après semaine.

Étape 7 — Enregistrer la définition

Ajoutez la spécification à reference/saved_reports.md avec la date de création et la cadence. C'est ce qui rend le rapport récurrent au lieu de ponctuel.

Si ce fichier ne peut pas être écrit — le dossier skill est en lecture seule dans la plupart des runtimes installés — écrivez la définition dans report-definitions.md dans le répertoire de travail du propriétaire à la place et indiquez où elle est allée. Une définition qui échoue silencieusement à l'enregistrement est le même bug qu'une non-enregistrement.

Si le propriétaire a demandé une cadence, confirmez-la en une ligne : « Enregistré. Je l'exécuterai le premier lundi de chaque mois. » La programmation est une propriété de ce skill — aucune commande distincte nécessaire.

Après l'exécution

Une ligne : le rapport a été exécuté et la définition est enregistrée. Puis l'étape suivante la plus pertinente, avec au plus deux autres à proximité :

• « Le pack hebdomadaire, selon le calendrier » exécute /report-pack pour envelopper ceci en contexte selon une cadence.
• « Comment va l'entreprise ? » exécute business-pulse pour le tableau autour de ces chiffres.
• « Prévision de trésorerie » exécute cash-flow-snapshot quand le rapport a soulevé une question de trésorerie.

Maximum trois offres. Ne répétez jamais une offre que le propriétaire a déclinée durant cette session.

Quoi ne pas faire

• N'interrogez pas le propriétaire sur un rapport qu'il a déjà défini. Vérifiez saved_reports.md en premier, toujours.
• Ne demandez pas la permission de tirer des données. Le skill a été invoqué. Exécutez-le.
• N'inventez pas un nombre. Si une source n'a rien retourné, écrivez « n/a » et nommez la source. Une supposition plausible dans un rapport que le propriétaire transmet à sa banque est un grave échec.
• Ne commencez pas par le tableau. Le résumé est le produit ; le classeur est l'annexe.
• Ne traitez pas « aucun connecteur » comme un blocage. Le chemin CSV est un mode de première classe.

Fichiers de référence

• reference/report_spec.md — le format de spécification, avec des exemples travaillés
• reference/data_sources.md — mappage métrique-connecteur, avec alternatives
• reference/output_template.md — structure exacte pour le résumé chat et le classeur
• reference/saved_reports.md — définitions de rapports enregistrés, ajoutées au fil du temps
• reference/gotchas.md — les modes de défaillance qui produisent des rapports confidentiellement faux

Utiliser un outil qui n'est pas listé

Les connecteurs nommés dans ce skill sont les chemins testés, pas une barrière. Si le propriétaire veut que ce flux utilise un outil qui n'est pas connecté ou listé, offrez build-connector — il vérifie d'abord le répertoire de connecteurs et se connecte via Zapier sinon, jamais une construction manuelle contre une API brute. Une fois la connexion établie, l'outil rejoint ce skill comme tout autre connecteur optionnel, sous les mêmes portails d'approbation.