learn

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

1. Determine the scope: does this apply to all projects or just one?
2. If cross-project, does it relate to a specific language or tool?
3. If language-specific, route to the corresponding convention skill
4. If general, route to instructions/global.md
5. If project-only, route to the project's AGENTS.md
6. If file-scoped enforcement only, create a .claude/rules/ entry

Kaizen Principles

1. Incremental > revolutionary — Smallest viable change, verify before next
2. Poka-yoke — Prefer hooks/tooling over prose instructions (error-proof by design)
3. Standards work — Follow existing patterns, document what works
4. JIT — Build only what is needed, optimize when measured

Verification Checklist

1. Verify against actual practice — confirm the pattern reflects real usage
2. Check for contradictions with existing instructions
3. Assess token impact — keep always-loaded content minimal
4. Get user approval — never modify instruction files without consent
5. Test the change — run python scripts/check.py after any instruction file edit

Critical Rules

1. Never modify instruction files without explicit user approval
2. Require 3+ corrections across 2+ sessions before promoting
3. Check for contradictions with existing instructions
4. Route to narrowest applicable scope (rule before skill, skill before global)
5. Keep always-loaded content under token budget
6. Run python scripts/check.py after every instruction file modification
7. 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 change
• correction pattern — a repeated fix that indicates a missing or wrong instruction
• token budget — the limit on always-loaded instruction content
• scope — cross-project, language-specific, orchestration, project-specific, or file-scoped

Validation Contract

Run from this skill directory before declaring changes complete:

python scripts/check.py

Completion criteria:

1. scripts/check.py exits 0.
2. No portable-CLI violations remain under this skill directory.