Entry Types

Lore categorizes engineering knowledge into four distinct, semantic types.

1. Decision

An architectural or technical choice, documented with its full rationale. Prevents teams from re-debating the same tradeoffs every quarter.

$ lore log --type decision \
  --title "Use Postgres over MongoDB" \
  --context "Our data is highly relational. Joins are critical for reporting." \
  --alternatives "MongoDB, DynamoDB" \
  --tradeoffs "Less flexible schema, but ACID compliance is worth it"

When to log one: Any time you make a technology, architecture, or design choice that future developers might question.

2. Invariant 🔴

A critical, unbreakable rule. If this invariant is violated, the system fails. These are the highest-priority entries — when connected via MCP, AI assistants will see these before they write any code.

$ lore log --type invariant \
  --title "All auth tokens must be validated on every request" \
  --context "Never cache auth results in memory. Always validate against the token store." \
  --files "src/middleware/auth.js"

When to log one: Security constraints, performance SLAs, data integrity rules, regulatory requirements.

3. Gotcha ⚠️

A non-obvious behavior, footgun, or issue that has bitten the team. Documented once so nobody wastes hours debugging the same problem.

$ lore log --type gotcha \
  --title "Date.now() in test fixtures produces flaky tests" \
  --context "Jest doesn't freeze time by default. Use jest.useFakeTimers()." \
  --tags "testing,dates"

When to log one: After debugging something that had a non-obvious cause, or discovering surprising API behavior.

4. Graveyard 🪦

An approach that was tried and abandoned, with a record of why it failed. Prevents new team members from re-attempting approaches that have already proven unworkable.

$ lore log --type graveyard \
  --title "Tried GraphQL for the public API" \
  --context "Removed in v2 due to N+1 queries killing the DB. REST is simpler for our use case."

When to log one: When removing a feature, reverting a major change, or abandoning a proof-of-concept.

Entry Structure

Each entry is stored as a JSON file in .lore/entries/. The structure includes: