learnings/README.md

@@ -0,0 +1,88 @@
+# Learnings
+
+This folder captures learnings from retrospectives and day-to-day work. Learnings serve three purposes:
+
+1. **Historical record**: What we learned and when
+2. **Governance reference**: Why we work the way we do
+3. **Encoding source**: Input that gets encoded into skills, commands, and agents
+
+## The Learning Flow
+
+```
+Experience → Learning captured → Encoded into system → Knowledge is actionable
+                   ↓
+            Stays here for:
+            - Historical reference
+            - Governance validation
+            - Periodic review
+```
+
+Learnings are **not** the final destination. They are inputs that get encoded into commands, skills, and agents where Claude can actually use them. But we keep the learning file as a record of *why* we encoded what we did.
+
+## Writing a Learning
+
+Create a new file: `YYYY-MM-DD-short-title.md`
+
+Use this template:
+
+```markdown
+# [Title]
+
+**Date**: YYYY-MM-DD
+**Context**: What triggered this learning (task, incident, observation)
+
+## Learning
+
+The insight we gained. Be specific and actionable.
+
+## Encoded In
+
+Where this learning has been (or will be) encoded:
+
+- `skills/xxx/SKILL.md` - What was added/changed
+- `commands/xxx.md` - What was added/changed
+- `agents/xxx/agent.md` - What was added/changed
+
+If not yet encoded, note: "Pending: Issue #XX"
+
+## Governance
+
+What this learning means for how we work going forward. This is the "why" that justifies the encoding.
+```
+
+## Encoding Process
+
+1. **Capture the learning** in this folder
+2. **Create an issue** to encode it into the appropriate location
+3. **Update the skill/command/agent** with the encoded knowledge
+4. **Update the learning file** with the "Encoded In" references
+
+The goal: Claude should be able to *use* the learning, not just *read* about it.
+
+## What Gets Encoded Where
+
+| Learning Type | Encode In |
+|---------------|-----------|
+| How to use a tool | `skills/` |
+| Workflow improvement | `commands/` |
+| Subtask behavior | `agents/` |
+| Organization belief | `manifesto.md` |
+| Product direction | `vision.md` (in product repo) |
+
+## Periodic Review
+
+Periodically review learnings to:
+
+- Verify encoded locations still reflect the learning
+- Check if governance is still being followed
+- Identify patterns across multiple learnings
+- Archive or update outdated learnings
+
+## Naming Convention
+
+Files follow the pattern: `YYYY-MM-DD-short-kebab-title.md`
+
+Examples:
+- `2024-01-15-always-use-comments-flag.md`
+- `2024-01-20-verify-before-cleanup.md`
+- `2024-02-01-small-prs-merge-faster.md`