DEV Community: Kouamé Maïzan Alain Serge Kossonou

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

Kouamé Maïzan Alain Serge Kossonou — Thu, 07 May 2026 08:45:00 +0000

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.

Un hook post-commit.
Trois questions.
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.

Capture the decision at commit-time, or lose it forever

Kouamé Maïzan Alain Serge Kossonou — Thu, 07 May 2026 08:30:00 +0000

How many times have you faced code nobody can explain anymore?

A strange architectural choice. A cache TTL of 17 minutes that nobody can justify. A worker disabled with a // don't touch — breaks everything comment that doesn't say why. You go looking. You find nothing. The person who knew has left. The commits say fix, update, wip.

Or worse: you find documentation. But it contradicts itself. One page says authentication goes through OAuth. Another, written six months later, talks about JWT. Neither says which is obsolete. Neither says why the choice changed.

You stop trusting the docs. The absence of documentation is sometimes less crippling than documentation that lies without knowing it.

This isn't a discipline problem. It's a tool problem. Documenting takes time, breaks flow, and always ends up at the bottom of the priority pile.

I built a tool to fix that. It's called Lore.

And here's the part nobody admits: we're not careless. We just operate under the quiet assumption that we'll remember. The brain is a liar that way. At the moment of decision, the reasoning is vivid, load-bearing, obvious. A month later it's a sketch. Six months later it's a rumour.

Why the tools I already had weren't solving this

I'd tried. I wasn't starting from zero.

Tool	What it gave me	What it missed
Conventional Commits	The what (`feat:`, `fix:`, `refactor:`)	The why
ADR tools	The 5 decisions per quarter big enough to feel architectural	The hundred micro-decisions per week that become architectural once enough stack
Wikis / Confluence	Polished pages, decoupled from code	Up-to-date truth — every team I've been on has a wiki graveyard somewhere
Code comments	Inline rationale	Reviewer pressure: "this comment explains what — delete it" is a cliché for a reason
Swimm / GitBook / SaaS	Lovely UI	Coupling docs to proprietary infrastructure I don't own

The diagnosis I eventually arrived at: this is a timing problem, not a tooling problem.

Every existing solution asked me to document after — in a separate moment, through a separate tool, with separate friction. But the only moment I actually remember why is the moment I decide. Miss that moment, and no tool can bring it back.

The hypothesis

Capture the decision at commit-time, or lose it forever.

If the capture doesn't happen in the same breath as the work, it doesn't happen. And the only reliable heartbeat Git gives you is the commit.

So I started building.

What "at commit-time" looks like in practice

The design ended up being almost embarrassingly simple.

A post-commit hook.
Three questions.
A Markdown file next to your code.

Here's what a commit looks like now:

$ 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 was too memory-hungry at 5k req/s
  ✓ Captured: feature-add-rate-limiter-to-api-login.md

The first two prompts are pre-filled from the commit message. You just press Enter. The third one — the Why — is the one I actually have to type. That's the one that matters.

The file produced is plain Markdown with front-matter, sitting in .lore/docs/ inside your 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 was too memory-hungry at 5k req/s

That's it. No platform. No sync. No account. Markdown in your repo, committed alongside your code, searchable with grep or with lore show <keyword>.

What this looks like in a real repo

Don't take my word for it. Here's an actual entry from lore's own .lore/docs/ directory — captured at commit time, polished by Angela later, committed to the 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]
```

The Mermaid diagram in there? Suggested by Angela's polish step. The commit: SHA in the front matter? A live anchor — you can git show it. Clone the repo if you want to see the rest.

How the hook decides what to do

Before any prompt fires, lore evaluates a chain of contextual rules. Merge commits, rebases, cherry-picks, CI runs — none of them should drag you into a "Why?" question. The decision happens in milliseconds, and the first matching rule wins:

Source diagram (rendered live on GitHub): contextual-detection.md. Click through if you want to read the gates in detail.

That's the gate that keeps lore ambient. The hook only surfaces when a real decision shows up — typo fixes, mechanical merges, and CI commits stay invisible.

What I found after dogfooding this on my own project

I've been running lore on lore's own codebase. Not six months — the last seven weeks of real use. A few things surprised me.

Most commits don't deserve a lore entry, and that's fine. I thought I'd end up with a wall of noise. Instead, the [doc-skip] tag became my friend. Fix-fix-fix commits get skipped. The ratio surprised me: seven weeks in, my own repo has ~130 commits and two substantive lore docs covering the major decisions — not 130 entries for 130 commits. The hook fires often; the docs only stick when there's actually a why to capture.

The "Why" question is uncomfortable in the best way. Typing a sentence about why you just did something forces you to notice when you don't have a reason — when you're committing on autopilot. Twice in the first week, I hit the prompt, froze, and realized I'd copy-pasted a pattern from somewhere without thinking. Both times I went back and changed the code.

Searchable decision history beat "asking a colleague" for most of my queries. I solo this project, so the comparison isn't fair — but lore show "rate limit" or lore show "config cascade" got me the answer in under a second for every question where the answer existed. Faster than re-deriving it from code. Faster than git log spelunking.

The corpus started generating second-order value I didn't plan for. Release notes assemble themselves from the decision log. Onboarding becomes "read the last 20 entries". Audit trails come free. None of these were the goal. They just fell out.

What I got wrong (and am still fixing)

Not everything worked first try.

My initial design made all prompts mandatory. Even typo fixes asked "Why?". It was insufferable. Express mode + [doc-skip] came from that pain.
I initially stored entries in SQLite to make search fast. Then I realized the Markdown files were the database — SQLite is now just an index that gets rebuilt from the files. The Markdown is the source of truth.
I tried to make the hook work on merge commits by default. Bad idea. Merges are almost never decisions; they're mechanical. Contextual detection now skips merges, rebases, and cherry-picks unless you ask.

Angela, briefly

Since she'll come up: Angela is an opt-in AI reviewer for your decision corpus. She runs structural analysis entirely offline (no API key needed) — checking coherence, spotting contradictions, flagging gaps. The optional polish step uses an AI provider of your choice (Anthropic, OpenAI, or a local Ollama) and always shows you a diff before touching anything. Zero telemetry. No background calls.

She doesn't work alone. She leans on a system of expert personas — Affoué (the storyteller, who keeps the why clearer than the what), Ouattara (the API designer, for Postman contracts and technical specs), and others on the way. Not a generic AI — a team that knows your project.

The deep-dive on Angela — polish, review, multi-provider, the persona system — is the next post in this series. Follow if you want the notification.

Try it

Pick the install path that fits your platform:

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

# Go (any platform)
go install github.com/greycoderk/lore@latest

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

# Windows: download from https://github.com/GreyCoderK/lore/releases
# (Chocolatey package `lore-cli` arriving once moderation completes)

Then:

cd your-project
lore init

Make a commit. Answer the question. Open .lore/docs/ a week later and read yourself back.

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

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

Built with Go, dogfooded on itself.

The thing I actually want from you

If you've faced your own version of this — a commit you couldn't explain, a cache TTL that made no sense, a doc that contradicted another, a library you couldn't remember why you chose — drop it in the comments. I collect these stories. They're the most useful feedback I get, because they teach me what kinds of decisions lore still doesn't capture well.

The person who knew has left. Or is sitting at your keyboard a year later. Either way: let's fix that.