Learn — Capture and Route Project Knowledge
Record corrections, insights, and patterns. Route them to the correct instruction file. Apply kaizen principles to keep instructions lean and effective.
Dispatch
$ARGUMENTS | Action |
|---|
"<correction text>" | Route correction to appropriate instruction file |
review | Show pending learnings and their frequency |
promote | Promote high-frequency learnings (3+ occurrences) to instruction files |
audit | Check for stale, contradictory, or duplicate learnings |
| Empty | Display usage summary |
References
| File | Purpose |
|---|
references/routing-rules.md | Decision tree for where to route instruction changes |
references/kaizen-principles.md | Error-proofing patterns, when to use hooks vs prose vs rules |
Routing Protocol
Route proposed updates to the correct target:
| Scope | Target |
|---|
| Cross-project conventions | instructions/global.md |
| Language-specific tooling | Convention skill (python-conventions, etc.) |
| Orchestration/parallelism | orchestrator skill body |
| Project-specific standards | Project's AGENTS.md |
| File-scoped enforcement | .claude/rules/<topic>.md |
| Skill behavior | The skill's own SKILL.md |
Routing Decision Steps
- Determine the scope: does this apply to all projects or just one?
- If cross-project, does it relate to a specific language or tool?
- If language-specific, route to the corresponding convention skill
- If general, route to
instructions/global.md
- If project-only, route to the project's
AGENTS.md
- If file-scoped enforcement only, create a
.claude/rules/ entry
Kaizen Principles
- Incremental > revolutionary — Smallest viable change, verify before next
- Poka-yoke — Prefer hooks/tooling over prose instructions (error-proof by design)
- Standards work — Follow existing patterns, document what works
- JIT — Build only what is needed, optimize when measured
Verification Checklist
- Verify against actual practice — confirm the pattern reflects real usage
- Check for contradictions with existing instructions
- Assess token impact — keep always-loaded content minimal
- Get user approval — never modify instruction files without consent
- Test the change — run
wagents validate after any instruction file edit
Critical Rules
- Never modify instruction files without explicit user approval
- Require 3+ corrections across 2+ sessions before promoting
- Check for contradictions with existing instructions
- Route to narrowest applicable scope (rule before skill, skill before global)
- Keep always-loaded content under token budget
- Run
wagents validate after every instruction file modification
- Prefer hooks/rules over prose (poka-yoke principle)
Canonical Terms
instruction file — any file that provides agent instructions (global.md, AGENTS.md, SKILL.md)routing — the process of choosing the correct target file for a changecorrection pattern — a repeated fix that indicates a missing or wrong instructiontoken budget — the limit on always-loaded instruction contentscope — cross-project, language-specific, orchestration, project-specific, or file-scoped