lore-commits

Original：🇺🇸 English

Translated

Use when writing git commit messages for non-trivial changes — captures decision context (constraints, rejected alternatives, confidence, directives) as structured git trailers so future agents and developers can query project knowledge via git log --trailer=

5installs

Sourcetmdgusya/lora

Added on2026-07-26

NPX Install

npx skill4agent add tmdgusya/lora lore-commits

SKILL.md Content

View Translation Comparison →

Lore Commits

Overview

Every commit destroys decision context. You considered alternatives, evaluated tradeoffs, and chose one approach — but only the final diff survives. Lore reclaims this lost knowledge by encoding it as git trailers in commit messages.

Core principle: A commit is not a label for a diff — it's an atomic unit of institutional knowledge. Use git's native trailer format so decisions are machine-queryable, not buried in prose.

When to Use

Any commit where you made non-obvious decisions
When you rejected alternative approaches
When external constraints shaped your implementation
When future modifiers need warnings about fragile assumptions
When test coverage has known gaps

When NOT to use: Trivial changes (typo fixes, formatting) where no real decisions were made.

The Format

<imperative summary line>

<optional body explaining the change>

Constraint: <external constraint that shaped this decision>
Rejected: <alternative> | <reason it was rejected>
Confidence: <high | medium | low>
Scope-risk: <narrow | moderate | broad>
Reversibility: <clean | moderate | difficult>
Directive: <warning or instruction for future modifiers>
Tested: <what was verified>
Not-tested: <known coverage gaps>
Related: <commit hash or description of related commit>

All trailers are optional. Include only those that carry signal for this specific commit.

Trailer Vocabulary

Trailer	Purpose	Example
`Constraint:`	External limit that shaped the decision	`Auth service does not support token introspection`
`Rejected:`	Alternative considered and why it was dropped. Use `	` to separate alternative from reason
`Confidence:`	How sure you are this is right: `high` , `medium` , `low`	`high`
`Scope-risk:`	Blast radius: `narrow` , `moderate` , `broad`	`narrow`
`Reversibility:`	How easy to undo: `clean` , `moderate` , `difficult`	`clean`
`Directive:`	Warning to future modifiers — what NOT to do or what to check first	`Do not narrow 4xx handling without verifying upstream behavior`
`Tested:`	What was verified and how	`Single expired token refresh (unit)`
`Not-tested:`	Known gaps in verification	`Auth service cold-start > 500ms behavior`
`Related:`	Linked commits forming a decision chain	`abc1234 (initial auth interceptor)`

You can repeat trailers (multiple

Constraint:

, multiple

Rejected:

, etc.).

You can extend the vocabulary with custom trailers when needed (e.g.,

Deadline:

,

Stakeholder:

,

Migration:

).

Complete Example

Prevent silent session drops during long-running operations

The auth service returns inconsistent status codes on token
expiry, so the interceptor catches all 4xx responses and
triggers an inline refresh.

Constraint: Auth service does not support token introspection
Constraint: Must not add latency to non-expired-token paths
Rejected: Extend token TTL to 24h | security policy violation
Rejected: Background refresh on timer | race condition
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Error handling is intentionally broad (all 4xx)
  -- do not narrow without verifying upstream behavior
Tested: Single expired token refresh (unit)
Not-tested: Auth service cold-start > 500ms behavior

Why Git Trailers (Not Prose)

Agents naturally capture decision context as prose paragraphs. The problem: prose is not queryable.

Git trailers are a native git feature. Queryable with standard git tools:

bash

# Query all constraints affecting a file
git log --all --grep="^Constraint:" -- path/to/file.ts

# Find all rejected approaches
git log --all --grep="^Rejected:" -- path/to/file.ts

# Find directives (warnings for future modifiers)
git log --all --grep="^Directive:" -- path/to/file.ts

# Check what's not tested
git log --all --grep="^Not-tested:" -- path/to/file.ts

This turns your git history into a queryable decision database at zero infrastructure cost.

Agent Workflow

When modifying code, before committing:

Harvest context — What constraints did you face? What alternatives did you reject?
Write the summary line — Imperative, focused on why not what
Add body if the how needs explanation
Append trailers — One per decision fact. Only include trailers that carry signal.
Self-check — Would a future agent modifying this code benefit from knowing this?

Common Mistakes

Mistake	Fix
Writing trailers as prose paragraphs	Use `Key: value` format on separate lines
Putting trailers before the body	Trailers must come after the body, separated by a blank line
Omitting the reason in `Rejected:`	Always use `alternative
Adding trailers to trivial commits	Only add when real decisions were made
Duplicating diff content in trailers	Trailers capture what's NOT in the diff — the why, not the what
Using `Confidence: yes`	Use the scale: `high` , `medium` , `low`