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

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.

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.

1. A post-commit hook.
2. Three questions.
3. 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.