opi

name

opi

description

Extract learnings from recent git commits, the current conversation, and security reviews — both reactive fixes and preventive patterns. Routes each learning to ONE canonical home and fans out lightweight pointers to every relevant skill's learnings.md so it surfaces whichever skill a future session triggers. Use for "/opi", "opi", "mitä opittiin", "extract learnings", "add learning", end-of-session reflection, or after a security review / reusable-pattern creation.

Opi - Learning Extractor

Extract learnings from recent work to improve future Claude sessions. Captures two types:

1. Reactive — What went wrong and how it was fixed (bugs, corrections, failed attempts)
2. Preventive — Reusable patterns that prevent future problems (safe components, conventions, security defaults)

Workflow

Step 1: Gather Sources

# Recent commits (last 20)
git log --oneline -20

# Today's commits with details
git log --since="midnight" --format="%h %s"

# Fix/refactor/security commits
git log --oneline -50 | grep -iE "(fix|korja|refactor|bugfix|secur|safe|harden)"

Also check:

• Current conversation for corrections, discoveries, new patterns
• Recent security reviews or audit results
• New reusable components or utilities created this session

Step 2: Classify Each Finding

For each potential learning, determine the type:

Type	Signal	Example
Reactive fix	Bug fixed, user corrected, test failed	"useEffect infinite loop — wrap in useCallback"
Preventive pattern	New convention, safe default, reusable component	"Use SafeTextarea for user-facing text inputs"
Security hardening	Vulnerability found, RLS gap, input validation	"Always enforce maxLength on text inputs"
Anti-pattern	Repeatedly wrong approach discovered	"Don't use bare Textarea without maxLength"

Step 3: Route AND Fan Out

A learning is useless if it only lives where the bug happened — a future session usually triggers a different skill. So every learning gets one canonical home plus lightweight pointers in every other skill it touches.

See references/learnings-router.md for the full routing table and the fan-out procedure.

Step 3a — Pick the canonical home. One destination, where the full wrong/right detail lives:

Learning Domain	Canonical Home
React/TypeScript, Supabase/DB, CSS, i18n	.claude/LEARNINGS.md
Security patterns, input validation	.claude/LEARNINGS.md (Security section)
CI/CD	ci-doctor/references/learnings.md
Lint/formatting	lint-fixer/references/learnings.md
Tests	test-writer/references/learnings.md
Security audits, RLS	security-auditor/references/learnings.md
Supabase migrations	supabase-migration-writer/references/learnings.md
Aihe-/jaedatan kuratointi (pisteytys, siivous, kattavuus, merget)	Docs/context/topic-verse-curation.md jos yleistyy; muuten topic-manager/verse-topic-tagger learnings
Other skill-specific	[skill]/references/learnings.md

Prefer global .claude/LEARNINGS.md when the learning is cross-cutting — it's better visible everywhere than hidden in one skill.

A domain may have a CANON that outranks its skill learnings. Where one exists (see the row above, and Docs/context/README.md → Mihin tämä kirjataan?), the generalised rule goes to the canon and the case-level detail stays in references/learnings.md. Route by "does this generalise?", not by "which skill was I in". If you add a new canon, add a row to references/learnings-router.md in the same pass — an unrouted canon is one /opi run away from being bypassed.

Step 3b — Fan out pointers. Identify every other skill a future session might be in when this learning matters:

1. Open Docs/context/skills-map.md and scan the Trigger Keywords table. Any skill whose triggers overlap the learning's domain is a fan-out target (e.g. a lazy-load bug → performance-auditor, cinema-voice-architect, any skill that renders summaries).
2. In each target skill's references/learnings.md, add one line under a ## Pointers section — never duplicate the full entry (duplication drifts):

   - **[Short title]:** see canonical entry in `.claude/LEARNINGS.md#anchor`
   

3. Create a missing references/learnings.md from skill-creator/assets/learnings-template.md, then verify the receiving skill's SKILL.md actually links it (add a line if not — an unreferenced learnings.md is never read).

Step 4: Format Learnings

Reactive fix format:

### [Issue Title]
- **Pattern:** What triggers this mistake
- **Wrong:** ❌ The incorrect approach
- **Right:** ✅ The correct approach
- **Why:** Root cause

Preventive pattern format:

### [Convention Title]
- **Rule:** Always do X when Y
- **Wrong:** ❌ The old/unsafe way
- **Right:** ✅ The new/safe way
- **Why:** What this prevents
- **Since:** date or commit ref

Recent Corrections table row:

| Date | Issue | Fix | Applies To |

Step 5: Propose & Write

1. Present each proposed learning with its canonical home and the list of fan-out skills (from Step 3b)
2. User approves/rejects each
3. Write the full entry to the canonical file, then add one-line pointers to each fan-out skill's references/learnings.md
4. Commit changes

Learning Quality Criteria

Only propose learnings that are:

• Non-obvious — Claude wouldn't know without being told
• Actionable — Concrete wrong/right examples, not vague advice
• Recurring — Likely to come up again in this codebase
• Preventive OR Corrective — Either prevents future bugs or fixes repeated mistakes

Skip: Typo fixes, one-off configs, project-specific constants, things Claude already knows.

Preventive Patterns to Watch For

When analyzing commits, specifically look for these signals that indicate a preventive learning:

Signal in Commit	Learning Type
New reusable component created	"Always use X instead of Y" convention
Security hardening (maxLength, validation, RLS)	Security default rule
feat(security): or fix(security): prefix	Security learning
Wrapper/helper replacing bare primitive	Anti-pattern (bare primitive) + convention (use wrapper)
Migration adding constraints/checks	DB convention
New utility extracted from repeated code	"Use X utility" convention

Commands Reference

# Commits since specific date
git log --since="2025-01-10" --oneline

# Commits by pattern
git log --all --oneline | grep -i "fix"

# Show specific commit
git show <hash> --name-only

# Diff for a commit
git diff <hash>^..<hash>

# Security-related commits
git log --oneline -50 | grep -iE "(secur|rls|grant|xss|valid|sanitiz|safe|harden)"