lessons-learned

lessons-learned

Stop repeating Claude's mistakes. Every session, automatically.

flowchart LR
    A["Claude makes\na mistake"] --> B["Emits #lesson tag\nor scanner detects it"]
    B --> C["Candidate in\nlessons.db"]
    C --> D["Review and promote\nvia /lessons:review"]
    D --> E["lesson-manifest.json\nrebuilt"]
    E --> F["Next session:\nPreToolUse hook"]
    F --> G{"Pattern\nmatches?"}
    G -- Yes --> H["Warning injected\nbefore tool call"]
    G -- No --> I["Silently skipped"]
    H --> J["Mistake avoided"]

# Step 1 — add the marketplace (once per machine)
claude plugin marketplace add joeblackwaslike/agent-marketplace

# Step 2 — install the plugin
claude plugin install lessons-learned@agent-marketplace

• Captures mistakes from session logs — structured tags and heuristic scanning
• Injects relevant warnings before tool calls at the exact moment they're needed
• Compounds — every session adds to a persistent store that follows you across projects

---

Why this exists

Claude is stateless. Every session forgets every correction, every footgun hit, every git stash that silently dropped untracked files. Over long agentic runs, the same class of mistake appears again and again — because nothing carries forward.

lessons-learned creates a persistent, compounding memory of failure patterns. Mistakes are captured automatically from session logs. A background scanner extracts candidates, you promote the ones worth keeping, and the next time Claude is about to make the same move, a warning surfaces at the exact tool call where it matters.

The feedback loop tightens over time. The more sessions, the stronger the prevention.

---

See it in action

Step 1 — Claude makes a mistake and emits a lesson tag:

#lesson
tool: Bash
trigger: git stash
problem: git stash silently omits untracked files — they stay in the working tree
         and are not stashed. Running git stash with new files present loses them.
solution: Use `git stash -u` (or `--include-untracked`) to capture all changes.
tags: tool:git, severity:data-loss
#/lesson

Step 2 — Next session startup scans the log:

$ node scripts/lessons.mjs scan --verbose
[scan] Scanning ~/.claude/projects/ for new lessons...
[scan] Processing session: abc123-2024-01-15.jsonl (42.3 KB)
  → tier1: found 1 structured lesson tag (#lesson)
  → tier2: found 1 heuristic pattern (error→correction)
[scan] Processing session: def456-2024-01-16.jsonl (38.1 KB)
  → tier1: no structured tags
  → tier2: no patterns detected
[scan] New candidates: 2 | Duplicates skipped: 0 | Total in DB: 47

Step 3 — Review and promote:

$ node scripts/lessons.mjs review --batch=1
── tool:git (1) ──────────────────────────────────────────

CANDIDATE: git-stash-untracked-files-a3f1
  Tool: Bash  Priority: 7  Confidence: 0.92
  Trigger: git stash
  Problem: git stash silently omits untracked files, risking data loss
  Solution: Use git stash -u to include untracked files

  Validation: PASS (length ok, no placeholders, no duplicates)

Promote? [y]es / [n]o / [s]kip / [q]uit: y
✓ Promoted git-stash-untracked-files-a3f1 → active
[build] Manifest rebuilt: 48 lessons included

Step 4 — Warning fires before the next git stash:

# Claude is about to run: git stash

⚠ Lesson: git stash silently omits untracked files

Problem: git stash silently omits untracked files, risking data loss.
Running git stash when new/untracked files are present does NOT stash them.

Fix: Use `git stash -u` (or `--include-untracked`) to capture all changes.

---

Install