lema · docs
The why, not the what
Documentation and code tell you what a system does. They rarely tell you why — which alternatives were argued and ruled out, which constraints still bind, what each choice commits you to. lema records that why as typed, cited claims.
Typed claims
Every claim carries a type, so an agent can tell a commitment from a casualty:
- chosen — the option that won.
- rejected — an alternative that was argued and ruled out — the why-not no other tool surfaces.
- constraint — a rule the choice must keep holding.
- consequence — what the choice commits you to next.
On a real question, the four types arrive together — here, for “why did React move from classes to Hooks?”
- chosen· reactjs/rfcs#68
Hooks let function components hold state and lifecycle, so stateful logic can be reused without wrapper components.
- rejected· reactjs/rfcs#68
A mixins-style sharing mechanism was ruled out before Hooks — name collisions and implicit dependencies.
- constraint· rules of hooks
Hooks are called at the top level in the same order each render — never inside conditionals or loops.
- consequence· reactjs/rfcs#68
Classes stay supported; Hooks were additive and opt-in, not a migration mandate.
Summarized, not quoted
A claim is a faithful summary of the record — the record indicates…— not a verbatim quote lifted out of context. The summary is what fits an agent’s budget; the source is always one step away to read in full.
Citations
No claim renders without its source. Every chosen, rejected, constraint, and consequence points back to the ADR, pull request, or issue it came from — so you can verify it yourself, and so a superseded decision can never quietly cite as if it were still in force.