Docs / AI-native / Logging decisions

Logging decisions

Git history tells you what changed. It rarely tells you why, and "why" is exactly what a future session (an AI assistant, or you six months later) has to reverse-engineer before it can safely extend anything. Keel's answer is memory/decisions.md: a running, ADR-style log of the calls you make on top of the starter.

When to log

Add an entry whenever you make an architectural call a future session would otherwise have to reconstruct from a diff:

• a new table or schema change
• a new billing rule or pricing tweak
• an auth change (a new Better Auth option, a new provider)
• any non-obvious choice with a real reason behind it

Small, self-explanatory changes don't need an entry. The bar is "would someone reading only the diff misunderstand this, or undo it by accident."

AGENTS.md at the repo root points every AI coding tool here, and instructs it to append an entry after making such a change. That's what keeps the habit alive without you remembering to ask.

Where it fits

memory/decisions.md starts empty on purpose. It's for your product's decisions. Everything Keel itself decided already lives in memory/architecture.md (the why behind the codebase) and memory/conventions.md (the day-to-day rules). Keeping your log separate means your decisions never get tangled up with Keel's.

Entry shape

decisions.md ships with a template at the top. Each entry is a dated ## heading and a short paragraph, that's it:

## 2026-07-01, Projects are team-scoped, soft-deleted
Added a projects table scoped by team_id (same pattern as the
rest of the schema). Soft delete via deleted_at so we can offer
a 30-day restore window. Hard-delete job runs nightly.

The heading carries the date and the decision in one line. The body covers the why and what it affects: the reasoning, which files moved, and any gotcha the next person needs (config flags flipped, a hook wired up, a rule that had to match an existing one). Aim for a few sentences, not an essay. Thirty seconds of writing now saves an hour of guessing later.