jrswab Provenance Log
LOG.md selectively preserves project-level rationale that code alone cannot safely convey.
Sequence
- Read LOG.md and the change context. Identify the decision, its rationale, and any rejected alternative.
- Complete when: you can answer, “Could removing this rationale cause a future session to make a plausible but incorrect change?”
- If the answer is no, add nothing.
- Complete when: LOG.md is unchanged; routine “what changed” details are not logged.
- If the answer is yes, append one concise entry under a descriptive heading. Include an available PR number; omit dates because Git supplies them.
- Complete when: the entry names the decision and preserves the rationale needed to prevent that incorrect change.
- Re-read the entry.
- Complete when: it explains why, not merely what changed or how the code works.
Reference
Typical decisions worth preserving include why:
- similar concepts remain separate;
- a path fails closed rather than falls back;
- an integration differs from the obvious implementation;
- a source is authoritative;
- validation occurs at a specific boundary;
- an apparently redundant field, state, or check remains;
- a serious alternative was rejected; or
- a compatibility constraint remains.
Use this shape when it fits:
Short decision name
PR: #123
[The decision, its rationale, and—when useful—the rejected alternative.]
Use AGENTS.md for a major architectural rule, not an ordinary implementation decision. Keep function-specific rationale in a code comment; important safety decisions may also appear in LOG.md because the two locations serve different retrieval paths.