wyattowalsh 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
python scripts/check.pyafter 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
python scripts/check.pyafter 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
Validation Contract
Run from this skill directory before declaring changes complete:
python scripts/check.py
Completion criteria:
scripts/check.pyexits 0.- No portable-CLI violations remain under this skill directory.