Capturer la décision à l'instant du commit, ou la perdre à jamais

Combien de fois t'es-tu retrouvé face à du code que personne ne comprend plus ?

Un choix d'architecture étrange. Un TTL de cache à 17 minutes que personne ne sait justifier. Un worker désactivé avec un // ne pas toucher — ça casse tout qui ne dit pas pourquoi. Tu cherches. Tu ne trouves rien. La personne qui savait est partie. Les commits disent fix, update, wip.

Ou pire encore : tu trouves de la documentation. Mais elle se contredit. Une page dit que l'authentification passe par OAuth. Une autre, écrite six mois plus tard, parle de JWT. Aucune ne dit laquelle est obsolète. Aucune ne dit pourquoi le choix a changé.

Tu ne sais plus à quelle doc faire confiance. L'absence de documentation devient parfois moins handicapante qu'une documentation qui ment sans le savoir.

Ce n'est pas un problème de discipline. C'est un problème d'outil. Documenter coûte du temps, casse le flow, et finit toujours en bas de la pile des priorités.

J'ai construit un outil pour résoudre ça. Il s'appelle Lore.

Et le plus troublant, c'est qu'on n'est pas négligents. On fonctionne juste sur le postulat tranquille qu'on se souviendra. Le cerveau ment de cette façon. Au moment de la décision, le raisonnement est vif, porteur, évident. Un mois plus tard, c'est une esquisse. Six mois plus tard, c'est une rumeur.

Pourquoi les outils que j'avais déjà ne résolvaient rien

Ce n'est pas faute d'avoir essayé.

Outil	Ce que ça m'a donné	Ce qui manquait
Conventional Commits	Le quoi (feat:, fix:, refactor:)	Le pourquoi
ADR tools	Les 5 décisions par trimestre assez "architecturales" pour mériter une cérémonie	Les cent micro-décisions par semaine qui deviennent l'architecture une fois cumulées
Wikis / Confluence	Pages polies, découplées du code	La vérité à jour — chaque équipe a son cimetière de wiki quelque part
Commentaires de code	Le pourquoi inline	La pression du reviewer : "ce commentaire explique le quoi — supprime-le" est un cliché pour une raison
Swimm / GitBook / SaaS	Belles UI	Le couplage à une infrastructure propriétaire que je ne possède pas

Le diagnostic auquel j'ai fini par arriver : c'est un problème de timing, pas un problème d'outil.

Toutes les solutions existantes me demandaient de documenter après — dans un autre moment, avec un autre outil, moyennant une autre friction. Or le seul moment où je me souviens vraiment du pourquoi, c'est le moment où je décide. Rate ce moment, et aucun outil ne me le rendra.

L'hypothèse

Capturer la décision à l'instant du commit, ou la perdre à jamais.

Si la capture n'a pas lieu dans le même souffle que le travail, elle n'aura pas lieu. Et le seul battement régulier que Git te donne, c'est le commit.

Alors j'ai commencé à construire.

À quoi ressemble "à l'instant du commit"

Le design final est d'une simplicité presque gênante.

1. Un hook post-commit.
2. Trois questions.
3. Un fichier Markdown à côté de ton code.

Voici à quoi ressemble un commit, maintenant :

$ git commit -m "feat: add rate limiter to /api/login"
  [1/3] Type [feature]:
  [2/3] What [add rate limiter to /api/login]:
  [3/3] Why? Token bucket — sliding window trop gourmand en mémoire à 5k req/s
  ✓ Capturé : feature-add-rate-limiter-to-api-login.md

Les deux premières questions sont pré-remplies depuis le message de commit. Tu tapes juste Entrée. La troisième — le Pourquoi — c'est celle que je dois vraiment taper. C'est celle qui compte.

Le fichier produit est du Markdown simple avec front-matter, dans .lore/docs/ à la racine de ton repo :

---
type: feature
date: 2026-02-14
commit: a3f9c2e
---

# feat: add rate limiter to /api/login

## What
Add rate limiter to /api/login

## Why
Token bucket — sliding window trop gourmand en mémoire à 5k req/s

Voilà. Pas de plateforme. Pas de sync. Pas de compte. Du Markdown dans ton repo, commit à côté de ton code, cherchable avec grep ou avec lore show <mot-clé>.

À quoi ça ressemble dans un vrai repo

Ne me crois pas sur parole. Voici une entrée réelle du .lore/docs/ de lore lui-même — capturée au commit, polie par Angela ensuite, commit dans le repo :

---
type: feature
date: "2026-04-10"
commit: 606cb47ae4807b725d7824dada67314311f20792
status: draft
generated_by: pending
angela_mode: polish
---

# Enable Chocolatey Package Distribution and Embedded Logo

## Why

Lore currently requires manual installation via GitHub releases or
building from source. This creates friction for Windows developers
who expect `choco install lore` to work.

## What Changed

- **Chocolatey package**: Windows package manager integration
- **Embedded logo**: Binary includes logo assets for notifications

## How It Works

```mermaid
graph TD
    A[Build Process] --> B[Embed Logo Assets]
    A --> C[Generate Chocolatey Package]
    B --> D[Binary with Icons]
    C --> E[choco install lore]
```

Le diagramme Mermaid là-dedans ? Suggéré par l'étape polish d'Angela. Le SHA commit: dans le front matter ? Une ancre vivante — tu peux faire git show dessus. Clone le repo si tu veux voir le reste.

Comment le hook décide quoi faire

Avant qu'une seule question ne s'affiche, lore évalue une chaîne de règles contextuelles. Merge, rebase, cherry-pick, run CI — aucun de ces cas ne devrait t'embarquer dans un "Pourquoi ?". La décision tient en quelques millisecondes, et la première règle qui matche gagne :

Diagramme source (rendu en direct sur GitHub, où Mermaid est natif) : contextual-detection.md. Clique pour lire les portes en détail — doc-skip, gestion rebase/merge/cherry-pick, le scoring du Decision Engine, et la cascade de fallback VS Code IPC pour les contextes non-TTY.

C'est cette porte qui garde lore ambiant. Le hook ne sort de l'ombre que quand une vraie décision se présente — fix-fix-fix, merges mécaniques et commits CI restent invisibles.

Ce que j'ai trouvé après avoir dogfoodé sur mon propre projet

Je fais tourner lore sur le codebase de lore lui-même. Pas six mois — les sept dernières semaines d'usage réel. Plusieurs choses m'ont surpris.

La plupart des commits ne méritent pas d'entrée lore, et c'est très bien. Je pensais finir avec un mur de bruit. Au lieu de ça, le tag [doc-skip] est devenu mon ami. Les commits de type fix-fix-fix passent au travers. Le ratio m'a surpris : sept semaines plus tard, mon repo a ~130 commits et deux entrées lore substantielles qui couvrent les décisions majeures — pas 130 entrées pour 130 commits. Le hook se déclenche souvent ; les docs ne tiennent que quand il y a vraiment un pourquoi à capturer.

La question "Pourquoi ?" est inconfortable de la meilleure des façons. Taper une phrase sur ce qu'on vient de faire oblige à remarquer les moments où on n'a pas de raison — où on commit en pilotage automatique. Deux fois dans la première semaine, j'ai bloqué devant la question, réalisé que j'avais copié un pattern sans réfléchir. Les deux fois, j'ai rouvert le code et je l'ai changé.

La recherche dans l'historique des décisions a battu "demander à un collègue" pour la plupart des questions. Je suis solo sur ce projet, donc la comparaison est biaisée — mais lore show "rate limit" ou lore show "config cascade" m'a donné la réponse en moins d'une seconde pour chaque question où la réponse existait. Plus rapide que redéduire depuis le code. Plus rapide que fouiller git log.

Le corpus a commencé à produire une valeur de second ordre que je n'avais pas prévue. Les release notes s'assemblent toutes seules depuis le journal de décisions. L'onboarding devient "lis les 20 dernières entrées". Les audits trails viennent gratuitement. Aucun de ces bénéfices n'était l'objectif initial. Ils sont tombés en plus.

Ce que j'ai raté (et ce que je continue de corriger)

Tout n'a pas marché du premier coup.

• Mon design initial rendait toutes les questions obligatoires. Même les typo fixes demandaient "Pourquoi ?". C'était insupportable. Express mode et [doc-skip] sont nés de cette douleur.
• J'avais initialement stocké les entrées en SQLite pour accélérer la recherche. Puis j'ai réalisé que les fichiers Markdown étaient la base de données — SQLite est maintenant juste un index reconstruit depuis les fichiers. Le Markdown est la source de vérité.
• J'avais voulu que le hook fonctionne aussi sur les merges. Mauvaise idée. Les merges ne sont presque jamais des décisions ; ils sont mécaniques. La détection contextuelle skippe maintenant les merges, rebases et cherry-picks sauf demande explicite.

Angela, brièvement

Puisqu'elle va venir dans la discussion : Angela est une reviewer IA opt-in pour ton corpus de décisions. Elle fait de l'analyse structurelle entièrement offline (pas de clé API nécessaire) — cohérence, contradictions, lacunes. L'étape polish optionnelle utilise un fournisseur IA de ton choix (Anthropic, OpenAI, ou un Ollama local) et te montre toujours un diff avant de toucher quoi que ce soit. Zéro télémétrie. Aucun appel en arrière-plan.

Et elle ne travaille pas seule. Elle s'appuie sur un système de personas experts — Affoué (la conteuse, qui veille à ce que le pourquoi soit toujours plus clair que le quoi), Ouattara (le designer d'API, pour les contrats Postman et les spécifications techniques), et d'autres en chemin. Pas une IA générique — une équipe qui connaît votre projet.

Le deep-dive sur Angela — polish, review, multi-provider, le système de personas — c'est le prochain post de cette série. Follow si tu veux la notification.

Un mot sur d'où vient ce projet

Je suis dev fullstack, solo, depuis la Côte d'Ivoire. Certains me connaissent sous Museigen (無制限, "sans limites" en japonais) — pas par arrogance, mais parce que je refuse l'idée que ce qu'on peut construire soit limité par l'endroit où on est né.

Lore est, entre autres choses, ma tentative de construire quelque chose fait pour durer — open source, bilingue EN/FR, utilisable à vie, zéro plateforme. Un outil qu'on peut utiliser sans rien devoir à personne.

Essaie-le

Choisis le chemin d'installation qui colle à ta plateforme :

# Homebrew (macOS / Linux)
brew install GreyCoderK/tap/lore

# Go (toutes plateformes)
go install github.com/greycoderk/lore@latest

# Script (macOS / Linux)
curl -sSfL https://raw.githubusercontent.com/GreyCoderK/lore/main/install.sh | sh

# Windows : télécharge depuis https://github.com/GreyCoderK/lore/releases
# (Le package Chocolatey `lore-cli` arrive dès la fin de modération)

Puis :

cd ton-projet
lore init

Fais un commit. Réponds à la question. Ouvre .lore/docs/ une semaine plus tard et relis-toi.

📚 Docs : greycoderk.github.io/lore — guides, configuration, philosophie, comparaison vs ADR/Conventional Commits/wikis

📦 Repo : github.com/GreyCoderK/lore — issues, discussions, AGPL-3.0

Fait en Go, dogfoodé sur lui-même.

Ce que je veux vraiment de toi

Si tu as vécu ta propre version de tout ça — un commit dont tu n'expliquais plus le choix, un TTL absurde, une doc qui contredisait une autre, une lib que tu ne te rappelles plus pourquoi tu l'as prise — raconte-le en commentaire. Je collectionne ces histoires. C'est le feedback le plus utile que je reçois, parce qu'il me montre les types de décisions que lore ne capture pas encore bien.

La personne qui savait est partie. Ou elle est assise à ton clavier un an plus tard. Dans les deux cas : corrigeons ça.