lore-commits
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=
How do I install this agent skill?
npx skills add https://github.com/tmdgusya/lora --skill lore-commitsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides guidelines for structured git commit messages using trailers to document decision context. It does not include executable code or external dependencies, and no security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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:
# 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 |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/tmdgusya/lora/lore-commits">View lore-commits on skillZs</a>