lessons-learned

Lessons Learned Extractor

Review the full conversation history, identify moments where something went wrong or required correction, and append structured lessons to docs/claude_logs/LESSONS_LEARNED.md in the current working directory.

---

What counts as a lesson

Scan the conversation for:

• Corrections — the user had to ask you to redo, move, rename, or restructure something
• Failed commands — a tool call errored and required a follow-up to fix it
• Misunderstood requirements — you built something in the wrong place, wrong format, or wrong scope
• Wrong assumptions — you assumed something that turned out to be false
• Sequencing mistakes — you did steps out of order or skipped a prerequisite

Do NOT capture:

• Things that worked correctly the first time
• Routine tool use (reading files, running standard commands)
• User preference changes that weren't errors (e.g. "actually let's rename this")

The target audience for each lesson is a future LLM reading it cold — write so the next session avoids repeating the same mistake, not as a narrative for the human.

---

Output format

Each lesson uses this structure:

## YYYY-MM-DD — <short title describing the mistake>

**What happened:** One or two sentences describing the concrete mistake or misunderstanding
that occurred in this session.

**Lesson:** One or two sentences stating the actionable rule or check to apply next time
to avoid repeating this.

• Use today's actual date (from system context or date command if needed)
• Title should name the mistake, not the fix (e.g. "mv requires parent directory to exist", not "use mkdir before mv")
• Keep each entry under 6 sentences total — dense and specific beats thorough and vague
• Prefer file paths, command names, and exact decisions over abstract descriptions

---

File handling

1. Check whether docs/claude_logs/LESSONS_LEARNED.md exists in the current working directory
2. If it does not exist, create it (including any missing parent directories) with this header before appending:

   # Lessons Learned
   
   ---
   

3. Append new lessons at the very end of the file — after the last existing entry, not before it. Never insert between existing entries.
4. Use the Write tool to rewrite the full file with the new lesson appended at the bottom, or use the Edit tool with the final line(s) of the file as the old_string anchor so the insertion lands at the true end.
5. Separate each new lesson from the previous content with a blank line

---

After writing

Tell the user:

• How many lessons were added
• The title of each one (one line each)
• If no lessons were found, say so explicitly rather than writing a placeholder entry