Learn

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):

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?

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

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.