Learn & Reflect

This skill should be used when the user asks to "record what we learned", "save lessons", "knowledge capture", "reflect on what happened", "write down experience", "what did we learn", "lessons learned", "retrospective", "log this plan", "what were we doing", "save plan log", or after completing a task that involved trial and error.

Learn: Explore, Reflect, Anneal

Capture knowledge and experience from work sessions. Turn mistakes into system improvements through structured reflection and self-annealing.

When to Use

• After completing a non-trivial task
• After encountering and fixing an error
• After discovering something unexpected
• When the user says "record this" or "what did we learn"

The Learning Cycle

Every learning opportunity follows this cycle:

Explore → Attempt → Observe Result → Reflect → Record → Anneal

1. Explore: What Did We Try?

Record the actions taken, in order:

• What was the goal?
• What approach did we choose and why?
• What alternatives did we consider?

2. Reflect: What Happened?

Analyze results honestly:

• What worked? Why?
• What failed? What was the root cause (not the symptom)?
• What surprised us?
• What assumption turned out to be wrong?

3. Record: Structured Knowledge Capture

Write each lesson in this format:

## [Topic]: [One-line summary]

**Context:** What we were doing when we learned this.
**What happened:** The specific event or error.
**Root cause:** Why it happened (not just what happened).
**Fix/Solution:** What we did to resolve it.
**Lesson:** The reusable knowledge (applicable beyond this specific case).
**Prevention:** What mechanism prevents this from happening again.

4. Anneal: Make the System Stronger

The most important step. A lesson that only lives in notes will be forgotten. Annealing means embedding the lesson into the system itself:

Error occurred
  → Fix the immediate problem
  → Update the tool/script that failed
  → Test the updated tool
  → Update the directive/documentation
  → System is now stronger against this class of error

Annealing targets (in order of durability):

Target	Durability	Example
Code/Script	Highest	Add validation, fix the bug, add error handling
Automated check	High	Add to pre-push script, CI check, linter rule
Directive/Playbook	Medium	Update the SOP with new step or warning
Memory/Notes	Lowest	Save as memory for future conversations

Always aim for the highest durability target. A lesson embedded in code cannot be forgotten.

Do / Don't Checklist

Do

• Record the root cause, not just the symptom
• Distinguish fact (verified, reproducible) from inference (likely but unproven) from assumption (believed but untested)
• Include the specific error message, file path, or command that triggered the learning
• Write lessons as reusable knowledge (applicable beyond the specific case)
• Embed prevention into tools/scripts when possible (annealing)
• Record what DIDN'T work (negative knowledge is valuable)
• Date the entry (knowledge has a shelf life)

Don't

• Don't record obvious things everyone knows
• Don't write vague lessons ("be more careful next time")
• Don't skip the root cause analysis ("it just broke" is not a lesson)
• Don't only record successes — failures teach more
• Don't reference external files that won't be available later
• Don't mix facts with assumptions without labeling them

The Reflection Process

When the user asks to reflect or record lessons, follow this exact process:

Step 1: Inventory List everything that happened in the session — actions, errors, fixes, discoveries.

Step 2: Classify For each event, ask: Is this a fact, inference, or assumption?

Type	Definition	Example
Fact	Verified by output, test, or tool	"API returns 404 when token is expired"
Inference	Likely based on evidence, but not directly tested	"The rate limit is probably per-IP based on the error pattern"
Assumption	Believed but not verified	"This endpoint probably supports pagination"

Step 3: Extract Lessons For each non-trivial event, write the structured lesson (Context → What happened → Root cause → Fix → Lesson → Prevention).

Step 4: Anneal For each lesson, identify the highest-durability target and implement the prevention mechanism.

Step 5: Verify Read back the recorded lessons. Ask:

• Is the root cause correct, or just a guess?
• Is the lesson specific enough to be actionable?
• Is the prevention mechanism actually implemented, or just written down?

Self-Annealing Examples

Weak annealing (just a note):

"Remember to check CI after pushing."

Strong annealing (embedded in tooling):

Added gh pr checks call to pre_push_check.py. Script now blocks if CI hasn't been checked. The lesson cannot be forgotten because the tool enforces it.

Weak annealing:

"Don't use \s in grep character classes."

Strong annealing:

Added shell script linter rule that flags \s inside [...]. Also added to the shell script checklist in the directive. Two layers of prevention.

Plan Log: Track Intent, Prevent Drift

Attention drift is real. You start with Plan A, get pulled into a side task, and forget what you originally set out to do. The Plan Log solves this.

How It Works

Every time a plan is created or a non-trivial task begins, save a timestamped snapshot:

PlanLog/
├── 202604111430_apify-skills-collection.md
├── 202604111600_clawhub-distribution.md
├── 202604111730_clawhub-deep-dive.md
└── 202604111800_learn-skill-update.md

Plan Log Entry Format

# Plan: [Title]
**Created:** YYYY-MM-DD HH:mm
**Status:** in-progress | completed | paused | abandoned
**Original goal:** [What we set out to do]

## Tasks
- [x] Completed task
- [ ] Pending task
- [ ] Task that got deferred

## Outcome
[What actually happened — filled in at the end]

## Drift Log
[If attention shifted, record when and why]
- HH:mm — Shifted to X because Y
- HH:mm — Returned to original plan / Decided to continue with X instead

When to Write a Plan Log Entry

• When entering plan mode or starting a multi-step task
• When the user says "let's do X" and X is non-trivial
• When you notice attention has drifted from the original goal

When to Review the Plan Log

• At the start of a new session (read recent entries for context)
• When unsure what was supposed to happen next
• When the user asks "what were we doing?" or "what's left?"
• Before declaring a task complete (check: did we finish what we planned?)

Attention Drift Checklist

• What was the original goal for this session?
• Are we still working toward it, or did we get pulled into something else?
• If we drifted, was it intentional (new priority) or accidental (got distracted)?
• Are there unfinished tasks from the original plan?
• Should we return to the original plan or update it?

Where to Save Knowledge

Knowledge type	Where to save
Technical fact (reusable)	Directive or knowledge base file
Project-specific context	Memory system or project notes
Tool bug or limitation	Comment in the tool's source code
Process improvement	Update the relevant SOP/playbook
One-time context	Don't save — it's ephemeral

Tips

• The best time to record is immediately after the event, while context is fresh.
• If you can't articulate the root cause, you haven't learned the lesson yet.
• A lesson without a prevention mechanism is a lesson that will repeat.
• Negative knowledge ("X doesn't work because Y") is often more valuable than positive knowledge.
• Date everything. Knowledge decays. APIs change. Tools update.