Create learnings/ folder with structure and template
Adds learnings folder for capturing insights from retros and daily work. Learnings serve as historical record, governance reference, and encoding source for skills/commands/agents. README includes: - Purpose explanation (historical + governance + encoding) - Learning template with all sections - Encoding process and destination guide - Periodic review guidance - Naming conventions Closes #39 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit was merged in pull request #46.
This commit is contained in:
88
learnings/README.md
Normal file
88
learnings/README.md
Normal file
@@ -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`
|
||||
Reference in New Issue
Block a user