Imported from Alexmacapple/alex-claude-skill (readme-causal/SKILL.md). Install upstream with npx skills add Alexmacapple/alex-claude-skill --skill readme-causal. Copyright stays with the author.

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 :

1. README existant — signale les gaps entre ce qui est dit et ce qui manque
2. git log --oneline -30 — révèle l'évolution du problème perçu par l'auteur
3. 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.

1. Vérifier le repo — .git/ présent ? Si non : signaler, continuer en lecture seule uniquement.
2. 3 lectures (voir § Collecte préliminaire) — JAMAIS sauter, même sous pression.
3. Détecter la langue — README + 5 premiers commits. Ambiguë → EN.
4. Triage — la demande active ce skill ? Si non → proposer un template README standard, arrêter.
5. 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]
6. Rédiger les 4 mouvements dans l'ordre : Anamèse → Étiologie → Ossature causale → Résidu.
7. Appliquer la politique de sortie selon l'état du README existant (absent / < 5 lignes / ≥ 5 lignes).
8. 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 :

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

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é :

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 :

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) :

Gestion des cas limites

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 :

• Langue détectée et cohérente dans tout le README
• Chaque section porte son marqueur de confiance ([IC]/[IE]/[FA]/[INC])
• Kairos : sourcé [IC], extrapolé [IE], question posée et répondue [FA], ou marqué [INC] — jamais inventé
• Résidu distinct d'une liste de fonctionnalités futures
• Politique de sortie appliquée (in-place / réécriture / diff)

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é.