Record a Lesson Learned

After fixing a bug, resolving an incident, or discovering an important pattern, record it for future sessions.

Steps

1. Classify the domain. Determine which memory file this belongs to:

• Pipeline/cron/Lambda/workers → memory/pipeline-ops.md
• Data quality/known bugs → memory/data-quality.md
• UI/frontend/navigation → memory/ui-navigation.md
• MCP server/CLI → memory/mcp-server.md
• Cross-cutting/general → memory/lessons-learned.md
• If it's a critical safety rule → also add to MEMORY.md (keep under 200 lines)

1. Check for contradictions. Read the target memory file and check:

• Does this contradict an existing entry? → Update the old entry, don't duplicate.
• Does this make an existing entry obsolete? → Remove or update it.
• Is there already an entry for this? → Strengthen it with new detail, don't duplicate.

1. Write the entry. Format:

   - **Short description (YYYY-MM-DD):** What happened, what the fix was, and the general rule to follow going forward.

• Always include the date.
• State the rule (what to do), not just the story (what happened).
• Keep it to 1-2 lines. Link to files/docs if details are needed.

1. Check staleness nearby. While editing, scan neighboring entries:

• Any entry with a date older than 30 days → verify it's still accurate or mark (verify).
• Any entry referencing a file path → quick-check the file still exists.
• Any entry with stats/counts → mark as (snapshot, may be stale) if not already marked.

1. Report. Tell the user what was added, what was updated, and any stale entries found.

Examples

Good entry:

- **Lambda timeout on large books (2026-03-13):** Books with >500 pages can exceed Lambda 15min timeout. Split into chunks of 400 pages max. See `src/lib/lambda-queue.ts:128`.

Bad entry (no date, no rule):

- Fixed the Lambda timeout issue.

When NOT to use this

• Trivial fixes (typos, one-line changes) — not worth recording
• Session-specific context — use handoffs instead
• Speculative conclusions from reading one file — verify first