Lessons Capture

Overview

Distills session experiences into transferable, project-scoped knowledge.

Core principle: Extract patterns that will help future sessions on this project.

Announce at start: "Applying lessons-capture skill to extract reusable patterns."

When to Use

• After completing a significant feature or bugfix
• When a pattern emerges that should be reused
• When discovering an anti-pattern to avoid
• When resolving a discrepancy (updating stale lesson)

[!IMPORTANT] Lessons persist in the PROJECT (

<workspace>/.ai-memory/lessons/

), not the conversation.

The Process

Step 1: Identify Lesson-Worthy Patterns

Ask:

• Did I solve a problem that will recur?
• Did I discover a project-specific constraint?
• Did I find an anti-pattern to avoid?

Step 2: Check for Existing Lessons

1. List

   <workspace>/.ai-memory/lessons/

2. If similar lesson exists: Update it with

   supersedes

   field
3. If new: Create fresh lesson

Step 3: Write the Lesson

Create

<workspace>/.ai-memory/lessons/<slug>.md

:

# Lesson: [Descriptive Title]

**Context**: [When this applies]
**Discovered**: YYYY-MM-DD
**Last Validated**: YYYY-MM-DD

## Pattern
[What to do - the reusable approach]

## Anti-Pattern
[What NOT to do - common mistakes]

## Evidence
- [Link to code or walkthrough showing this in action]

## Supersedes
- [Previous lesson file if updating, or omit]

Step 4: Verify Lesson Quality

• Is it general enough to apply to similar future work?
• Is it specific enough to be actionable?
• Does it include both pattern AND anti-pattern?

Common Mistakes

• Writing lessons too specific to one case
• Forgetting to link to evidence
• Not including the anti-pattern section
• Creating duplicate lessons instead of updating existing
• Using vague language ("handle appropriately")

Checklist

Before committing lesson:

• Has clear

  Context

  for when it applies
• Has concrete

  Pattern

  (what to do)
• Has concrete

  Anti-Pattern

  (what NOT to do)
• Links to evidence (code, walkthrough, PR)
• Checked for existing similar lessons

• Last Validated

  date is current