Files

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>

2026-01-07 20:17:31 +01:00

2.5 KiB

Raw Blame History

Learnings

This folder captures learnings from retrospectives and day-to-day work. Learnings serve three purposes:

Historical record: What we learned and when
Governance reference: Why we work the way we do
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:

# [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

Capture the learning in this folder
Create an issue to encode it into the appropriate location
Update the skill/command/agent with the encoded knowledge
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

2.5 KiB Raw Blame History