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
Don't
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
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.
