Extract reusable patterns from sessions and codify them as framework additions.
Extract reusable patterns from sessions and codify them as framework additions.
/learn)Watch for these signals during a session:
| Signal | Example | What to Extract |
|---|---|---|
| User correction | "No, use uv not pip" | Toolchain rule |
| Error-then-fix | mypy error -> fixed type annotation | Type safety pattern |
| Repeated workflow |
| Same 5 steps done 3+ times |
| Skill or command |
| Explicit preference | "Always use httpx" | Prohibited pattern |
| Gotcha discovered | API returns 200 on error | GOTCHAS.md entry |
Ask: Is this a one-off fix or a reusable pattern? Criteria for reusable:
If no to all three, log it in GOTCHAS.md and stop. Don't over-extract.
| Pattern Type | Goes Into | Example |
|---|---|---|
| Constraint ("always/never") | Rule file in rules/ | "Never use requests, use httpx" |
| Workflow ("how to do X") | Skill file in skills/ | "How to split a large file" |
| Shortcut ("run X quickly") | Command in commands/ | "Run all quality checks" |
| Persona ("act as X") | Agent in agents/ | "Review code as a security expert" |
| Automation ("do X on event") | Hook in hooks/ | "Auto-lint on file save" |
| Lesson ("X broke because Y") | GOTCHAS.md | "API returns 200 on auth failure" |
Before adding a new pattern:
Follow the contract in CONTRIBUTING.md for the target category:
opencode.json if it's a command or agent{{CLI_COMMAND}} install if it should be globalNot all patterns are equally proven. Use this scale when deciding whether to promote a pattern:
| Confidence | Criteria | Action |
|---|---|---|
| Low (seen once) | Single occurrence, single project | Log in GOTCHAS.md only |
| Medium (seen 2-3x) | Repeated in one project, or seen in 2 projects | Create as project-level rule/skill |
| High (proven) | Seen in 3+ projects, or validated by testing | Promote to framework |
Instincts and patterns are scoped to prevent cross-project contamination. A React pattern from one project should not influence a CLI script in another.
| Scope | Stored In | Applies To |
|---|---|---|
| Project | Project's GOTCHAS.md or AGENTS.md | Only this project |
| Global | Framework's rules/ or skills/ | All projects |
A project-scoped pattern can be promoted to global when:
Patterns evolve through increasing confidence: Observation → GOTCHAS.md → Project rule → Framework skill/rule
Evolution triggers: Pattern reaches High confidence (3+ contexts), multiple related patterns can cluster into a single skill, or a workflow becomes complex enough for a command.
Process: Identify candidates → classify target category → extract and generalise → follow CONTRIBUTING.md contract → remove original project-level entries.
Turn the friction log from a passive record into an active improvement driver:
| Don't | Do Instead |
|---|---|
| Extract every user correction as a rule | Only extract patterns that are reusable across projects |
| Create rules for style preferences ruff handles | Let ruff handle formatting/style |
| Add a skill for a one-step operation | Use a command instead, or just document in AGENTS.md |
| Duplicate existing patterns with different wording | Extend or modify the existing pattern |
| Create hooks for things that should be manual | Only automate high-frequency, low-risk operations |
| Apply patterns from project A to project B blindly | Check project scoping before applying |
| Promote patterns to global too early | Wait for High confidence across multiple projects |
| Dump all session context into subagent prompts | Filter to relevant wisdom only |
| Skip capture because "I'll remember" | Write it down — compaction and new sessions won't |
When dispatching subagents, pass relevant session learnings to prevent repeated mistakes.
| Category | Example | Priority |
|---|---|---|
| Gotcha | "API returns 200 on auth failure — check response body" | High |
| Constraint | "This project uses uv, not pip" | High |
| Pattern | "All connectors follow the 4-tier pattern" | Medium |
| Decision | "User chose SQLite over Postgres for this project" | Medium |
| Preference | "User prefers explicit imports over barrel files" | Low |
| Discovery | "The process_order function also handles refunds" | Medium |
When starting a new subagent that should inherit session wisdom:
## Inherited Wisdom
### Must Know
- [Critical gotchas and constraints]
### Good to Know
- [Patterns and decisions]
### FYI
- [Preferences and discoveries]
Before passing a learning forward, ask: