Self Learn

• 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.