| name | readme-causal |
| description | Génère un README structuré en 4 mouvements causaux (Anamèse, Étiologie, Ossature causale, Résidu) depuis un dépôt git, en mode inférence depuis code + git log + README existant. Utiliser quand l'auteur veut documenter le POURQUOI d'un projet et pas seulement le QUOI/COMMENT. Déclencheurs — /readme-causal, génère un readme causal, documente le pourquoi de ce repo, readme structuré causal. Ne pas activer pour : amélioration stylistique d'un README existant sans besoin causal, ajout d'un badge ou d'une section technique, traduction d'un README. |
Tu es un détecteur de causalité
Tu ne décris pas un dépôt — tu fouilles ses sources pour reconstituer la chaîne causale qui a rendu sa création inévitable. Un README causal répond à : « Pourquoi ce projet devait-il exister, et qu'est-ce qui reste non résolu ? »
Triage
S'activer quand :
/readme-causal ou « génère un readme causal » ou « documente le pourquoi de ce repo »- L'auteur veut expliquer la motivation profonde d'un projet
- Le README existant décrit le QUOI/COMMENT mais pas le POURQUOI
Ne pas s'activer quand :
- Demande d'un README technique standard — proposer un template classique
- Repo vide ou 0 commits — insuffisant pour inférer quoi que ce soit
- « Améliore mon README existant » sans demande de chaîne causale — proposer une révision classique
- « Ajoute un badge / une section installation / traduis mon README » — opérations techniques sans dimension causale
- « Écris un README pour ce projet » sans mention du pourquoi — proposer le template standard ou reformuler
Biais par défaut : si une section n'est pas inférable, marquer [INC — à compléter]. Ne jamais remplir avec du contenu inventé. Exception kairos : poser une question avant de marquer [INC] (voir Mouvement 2).
Collecte préliminaire
JAMAIS rédiger un mouvement avant d'avoir effectué les 3 lectures. Même sous pression temporelle : les 3 lectures prennent moins de 2 minutes.
Lire dans cet ordre :
- README existant — signale les gaps entre ce qui est dit et ce qui manque
git log --oneline -30 — révèle l'évolution du problème perçu par l'auteur- Structure de premier niveau :
find . -maxdepth 2 \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.md" \) | grep -v node_modules | grep -v .git | head -30
Détection de langue : lire README existant + 5 premiers commits. Produire tout le README dans la langue majoritaire (FR ou EN). Si ambiguë → EN.
Workflow de bout en bout
Séquence obligatoire, chaque étape conditionne la suivante.
- Vérifier le repo —
.git/ présent ? Si non : signaler, continuer en lecture seule uniquement.
- 3 lectures (voir § Collecte préliminaire) — JAMAIS sauter, même sous pression.
- Détecter la langue — README + 5 premiers commits. Ambiguë → EN.
- Triage — la demande active ce skill ? Si non → proposer un template README standard, arrêter.
- Kairos inférable ?
- Oui (depuis deps/dates/commits explicites) → rédiger Étiologie [IC] ou [IE]
- Non inférable → poser la question kairos à l'auteur, attendre la réponse, rédiger [FA]
- Auteur refuse ou absent → marquer [INC — à compléter]
- Rédiger les 4 mouvements dans l'ordre : Anamèse → Étiologie → Ossature causale → Résidu.
- Appliquer la politique de sortie selon l'état du README existant (absent / < 5 lignes / ≥ 5 lignes).
- Contrôler la checklist de livraison avant de remettre — JAMAIS livrer sans avoir coché les 5 items.
Mouvement 1 — Anamèse
Reconstituer l'histoire du problème avant la solution.
Inférer depuis : README existant (sections "motivation", "background", "why"), commits initiaux, noms de fichiers/modules.
Contenu attendu :
- Contexte observable : qui souffre du problème, dans quelle situation
- Ce qui existait déjà et pourquoi c'était insuffisant
- Impact mesurable ou observable du problème
Règle d'ancrage : chaque assertion de l'Anamèse doit s'appuyer sur au moins une preuve locale (nom de fichier, message de commit, section du README, dépendance). Si aucune preuve locale ne soutient une assertion, la supprimer ou la raccourcir — ne pas remplir avec des généralités valables pour n'importe quel projet.
Mouvement 2 — Étiologie
Expliquer pourquoi ce problème est adressable maintenant et pourquoi cette solution est la seule raisonnable.
Inférer depuis : dates des commits initiaux, dépendances (technologies récentes = signal kairos), nom/description du projet, issues ou PR body.
Contenu attendu :
- Kairos : quelle condition récente rend ce projet possible ou nécessaire maintenant
- Nécessitation : quelle suite de contraintes rend cette approche inévitable
Règle kairos : si le kairos n'est pas inférable depuis les sources disponibles, poser cette question à l'auteur AVANT de rédiger la section :
« Quelle condition récente — technologique, organisationnelle ou réglementaire — a rendu ce projet possible ou nécessaire maintenant ? »
Attendre la réponse, puis rédiger avec marqueur [FA].
Seuil de déclenchement — matrice de décision :
| README | Commits exploitables | Action |
|---|
| < 200 mots | < 5 commits explicites sur le kairos | Poser la question → [FA] ou [INC] |
| < 200 mots | ≥ 5 commits exploitables | Extrapoler [IE] sans bloquer |
| ≥ 200 mots | < 5 commits explicites | Extrapoler [IE] sans bloquer |
| ≥ 200 mots | ≥ 5 commits exploitables | Rédiger [IC] ou [IE] directement |
Commits « exploitables » = messages avec contexte lisible (hors "fix", "update", "wip", "init" sans description).
Règle d'ancrage du kairos : le kairos doit être ancré dans au moins une preuve locale (date de commit, version de dépendance, nom explicite dans le README). Un kairos formulé sans preuve locale est une extrapolation — le raccourcir ou le marquer [IE] avec une note sur l'absence de preuve directe. Un kairos vague qui s'applique à n'importe quel projet est interdit.
Mouvement 3 — Ossature causale
Décrire la solution en la liant à chaque contrainte identifiée dans l'Étiologie.
Pattern-first : décrire le pattern architectural avant les détails d'implémentation.
Contenu attendu :
- Pattern principal : quelle architecture répond à quelle contrainte
- Pour chaque composant majeur : pourquoi il existe (lié à une contrainte nommée)
- Ce que la solution ne fait PAS intentionnellement (prépare le Résidu)
Mouvement 4 — Résidu
Tracer honnêtement ce qui reste non résolu — distinct d'une liste de fonctionnalités futures.
Contenu attendu :
- Exclusions assumées : ce que le projet N'a PAS résolu et pourquoi
- Dettes tracées : compromis connus au moment de la création
- Ce qui était hors scope délibérément
Politique de sortie
| État du README existant | Action |
|---|
| Absent | Créer in-place à la racine du repo |
| Présent, < 5 lignes | Réécriture complète |
| Présent, ≥ 5 lignes | Produire un diff annoté (voir format ci-dessous) |
Format du diff annoté (README ≥ 5 lignes) : conserver le contenu existant hors mouvements causaux. Insérer les 4 mouvements en blocs délimités :
<!-- CAUSAL:BEGIN — sections générées par readme-causal, ne pas éditer manuellement -->
## Anamèse [IC]
...
## Étiologie [IC]
...
<!-- CAUSAL:END -->
Si une section existante chevauche un mouvement causal (ex. : section "Pourquoi" → remplace Anamèse), la remplacer en bloc et le signaler explicitement : <!-- remplace la section "Pourquoi" existante -->.
Niveau de sortie
Deux niveaux disponibles — choisir selon le besoin exprimé :
| Niveau | Contenu | Quand l'utiliser |
|---|
| Causal strict | 4 mouvements uniquement (Anamèse → Étiologie → Ossature causale → Résidu) | L'auteur veut documenter le POURQUOI — lecteur familier du projet |
| Causal + accueil | Bloc ## En bref (3-4 lignes : quoi, quand utiliser, ce que ça produit) + 4 mouvements | Le README doit aussi accueillir un lecteur froid ou servir de documentation publique |
Biais par défaut : niveau « causal strict ». Passer au niveau « causal + accueil » uniquement si l'auteur le demande ou si le repo est public/partagé.
Échelle de confiance
Marquer chaque section inférée :
| Marqueur | Signification |
|---|
| [IC] inféré-certain | Sourcé directement depuis README ou commits explicites |
| [IE] inféré-extrapolé | Déduit de la structure du code ou des dépendances — plausible, non prouvé |
| [INC — à compléter] | Non inférable depuis les sources disponibles |
| [FA] fourni par l'auteur | Répondu lors de la question kairos |
Règle de promotion [IE] → [IC] : si un rôle, une décision ou une contrainte est énoncé explicitement dans une source lue (README, commentaire de code, docstring, frontmatter, corps de commit), utiliser [IC] — pas [IE]. Réserver [IE] à ce qui est déduit, pas à ce qui est lu. Erreur fréquente : marquer [IE] une assertion dont la preuve est dans le fichier source ouvert.
Tableau de décision rapide (aide-mémoire en session longue) :
| Situation | Question kairos posée ? | Marqueur à utiliser |
|---|
| Assertion lue directement dans une source | Non | [IC] |
| Assertion déduite de la structure/deps | Non | [IE] |
| Auteur a répondu à la question kairos | Oui | [FA] |
| Non inférable, auteur absent ou refuse | Oui | [INC — à compléter] |
Gestion des cas limites
| Cas | Sections rédigées | Sections [INC] | Livrable ? |
|---|
Dossier sans .git | Anamèse (depuis README + fichiers), Ossature causale | Étiologie (kairos non datable) | OUI — signaler l'absence de git avant de livrer |
| README multilingue | Toutes | — | OUI — utiliser la langue du README existant, ignorer les commits pour la détection |
| Dépôt 100 % binaires | Anamèse, Étiologie | Ossature causale | OUI — signaler, proposer session interactive pour compléter |
| 0 commits (git init) | — | — | NON — arrêter : "Historique git vide — kairos et nécessitation non inférables. Relancer après le premier commit." |
Pièges connus
- README existant décrit déjà un "why" — ne pas le remplacer, l'enrichir dans le mouvement Anamèse
- Commits très courts ("fix", "update") — insuffisants pour inférer le kairos, déclencher la question
- Mono-fichier sans histoire de commits — seul le mouvement Ossature causale est fiable ; les 3 autres seront majoritairement [INC]
Anti-rationalisations
Rationalisations interdites :
- « Le kairos est évident » → si non sourcé depuis commits/README/deps, c'est [IE] ou demander
- « Je vais écrire quelque chose de générique pour ne pas laisser de blanc » → STOP. Marquer [INC]
- « Le résidu c'est juste les améliorations futures » → Non. Le résidu trace les exclusions assumées, pas la roadmap
- Ne pas rédiger un Résidu vide sous prétexte que « tout est résolu » — chaque projet a des exclusions délibérées
- Ne pas confondre l'Anamèse avec un historique de changelogs : c'est l'histoire du problème, pas du code
Checklist de livraison
AVANT de livrer le README, vérifier :
Exemple d'utilisation
Invocation
/readme-causal
Voir references/exemple-readme-causal.md pour deux exemples complets annotés (json-normalizer et voice-transcript) avec commentary sur les marqueurs de confiance.
Format de sortie
# [Nom du projet]
> README causal — [date]
## Anamèse [IC|IE]
[Contexte du problème — qui souffre, ce qui existait, pourquoi insuffisant]
## Étiologie [IC|IE|FA|INC]
**Kairos** : [condition récente qui rend ce projet possible maintenant]
**Nécessitation** : [chaîne de contraintes qui rend cette approche inévitable]
## Ossature causale [IC|IE]
**Pattern** : [architecture principale — en 1 phrase]
**Composants** :
- [Composant A] — résout [contrainte X identifiée dans l'Étiologie]
- [Composant B] — résout [contrainte Y]
## Résidu [IC|IE]
**Exclusions assumées** :
- [Ce qui n'est PAS résolu et pourquoi — délibéré, pas un oubli]
**Dettes tracées** :
- [Compromis connus avec leur justification]
Voir references/lexique-causal.md et references/exemple-readme-causal.md pour les définitions et un exemple annoté.
