self-learn

What this skill does

Closes the Dogfooding Meta-Loop from the Open Source Framework v4.1.

Every non-trivial session on a framework-driven project produces lessons: patterns that worked, patterns that failed, gotchas hit, decisions made. Most tools let those lessons evaporate. This skill captures them, runs a quality gate, and proposes framework updates.

It is the reason the framework evolves. Framework v4.0 → v4.1 was a self-learn pass that folded llmwiki's learnings back into the parent Open Source Framework.

When to invoke

• User says "learn from this session", "what did we learn", "extract lessons", "distill this"
• After a substantial feature ships (especially if it required multiple debugging loops)
• At the end of a project phase — before moving to the next phase
• When the user fixes a bug that was caused by a missing framework rule
• When the user finds a pattern that should apply across projects
• At the end of a "monthly verification" pass (Phase 8 Maintain)

Do NOT invoke when:

• The session is trivial (single file change, typo fix)
• The session is still in progress (wait until the user says "done")
• The learnings are obvious or already codified in the framework

Workflow

1. Gather context. Read:
   • The recent session transcript (raw/sessions/<project>/<latest>.md or Obsidian session notes)
   • _progress.md to know the current phase
   • tasks.md to see what shipped
   • docs/framework.md to know the current framework state
   • CHANGELOG.md for what's already been logged
2. Extract candidate lessons. Look for:
   • Failed attempts — "X didn't work because Y" → candidate rule
   • Surprising wins — "X worked and I wouldn't have guessed" → candidate pattern
   • Repeated debugging loops — "I hit X three times this week" → candidate hard rule
   • Decisions — "I chose X over Y because Z" → candidate Project Type addition
   • Hints the user gave — "we need to always do X" → candidate steering rule
   • Gaps in the roadmap — items discovered during execution that weren't in the plan
3. Score each candidate on two axes:
   • Generality: does this apply only to this project, or to any project of this type, or to all projects? (project → type → framework)
   • Confidence: how many data points? (1 occurrence = anecdote, 2 = pattern, 3+ = rule)

4. Propose updates grouped by destination:

   Destination	When to update it
   .kiro/steering/<rule>.md (project-specific)	2+ data points in this one project
   docs/framework.md in the project repo	Learning applies to all projects of this type
   .framework/Framework.md (personal Obsidian copy)	Cross-cutting rule that applies to all open-source projects
   CHANGELOG.md	Every update gets logged as framework version bump
   New skill under .claude/skills/	Repeatable workflow that warrants its own invocation
   New phase in the pipeline	If the learning is about a missing step

5. Show the diff to the user before applying anything.
6. With approval, apply the changes:
   • Write the new steering rule / framework section / skill
   • Bump the framework version (e.g. v4.1 → v4.2) if the update is non-trivial
   • Update CHANGELOG.md with a ## vX.Y entry describing what was learned
   • Append a one-line note to _progress.md in the Learning Log section
7. Report what changed, with line counts and a list of destination files.

Output format

## Self-learn report: <project> / <date>

### Sources consulted
- <file 1>
- <file 2>

### Candidate lessons (scored)

| # | Lesson | Generality | Confidence | Destination |
|---|---|---|---|---|
| 1 | <lesson> | project \| type \| framework | 1 \| 2 \| 3+ | <file> |
| 2 | ... | ... | ... | ... |

### Proposed updates

**1. .kiro/steering/page-format.md — add rule**
```diff
+ ## New rule from self-learn
+ <content>

2. docs/framework.md — new section under Phase 5.5

+ ### New QA check from self-learn
+ <content>

Approval needed

Apply all proposed updates? (y/n)

## Hard rules

1. **Never update the framework silently.** Always surface the diff and ask.
2. **Never invent a learning from one data point.** If confidence is 1, mark it as a draft and wait for a second occurrence.
3. **Respect the framework hierarchy.** Project → Type → Framework. Don't promote a project-specific learning to a cross-cutting rule without 3+ data points across projects.
4. **Version-bump the framework** (e.g. v4.1 → v4.2) on any update to `docs/framework.md`. Update `CHANGELOG.md` in sync.
5. **Never touch code** as part of self-learn. This skill only touches docs, steering files, and framework versioning. Code changes go through the normal PR flow.
6. **Dogfood itself.** Self-learn should produce a session transcript that future self-learn passes can read.

## Example outcomes (from llmwiki's own history)

- Framework v4.0 → v4.1: added **Phase 1.25 Research** after discovering that cloning 15 reference repos up-front prevented 3+ hours of rework during Phase 3 Structure.
- Added **`.llmwikiignore`** rule after hitting sessions containing contract data that shouldn't enter the wiki.
- Added **live-session detection** (`<60 min`) after the converter read a file mid-write and produced a truncated markdown.
- Added **"no AI co-authored-by"** rule to `.kiro/steering/contributing-rules.md` after a first-run slip.

Each of these started as a single session observation and got promoted to a framework rule after the second or third occurrence.

## Related skills

- `project-maintainer` — runs the phase gates that surface the "we hit this 3 times" patterns.
- `llmwiki-query` — to look back at past sessions and count occurrences of a pattern.
- `llmwiki-sync` — to make sure the latest session is available before running self-learn.