Teaching mode
On this page
Teaching mode has the team teach you as it works, so every ticket also teaches you something about the craft. It is off by default. Turn it on when you are new to development, new to leading a team, or new to the kind of work a repo does.
The levels
learning.level takes one of three values:
- off: the team teaches nothing. This is the default.
- explain: at each step a lesson covers, the team adds a short "why this matters" line to the ticket's
docs/work/<KEY>/handoff.md. A lane that keeps no records says it in one sentence in chat instead. It never adds a stop. - coach: as explain, but first the team asks you in chat to guess, such as which lane you would pick or how severe a finding is, then shows its own answer and why. It asks only where a wrong guess is safe. Reply "skip" to see the answer straight away.
Where the team teaches
| Step | What you learn |
|---|---|
| Acceptance criteria | What makes a criterion testable |
| Lane choice | Why the work gets this much process |
| A gate fires | What risk the gate exists for |
| Review findings | What the severity means and what to fix first |
| Test failures | How to read a failure, and what a flaky test means |
| Escalations | Why the team moved the task to a stronger model |
Coach never asks you to guess at a gate, an escalation or a guardrail, before anything outward-facing (a push, a pull request, a merge, a deploy), or at a stop where you must weigh a real risk. Those steps are explained, never guessed.
Guardrail lessons
When a guardrail holds or refuses a command and the level isn't off, the hold shows why the command is risky and what to do instead, and Claude tells you the same when it doesn't run. For example, for git reset --hard: it throws away every uncommitted change, so commit or stash the work first.
Your progress
Each topic (such as testing, migrations, tenant isolation, git or security) moves through three stages:
- Explained: you have met a lesson on it.
- Predicted: you guessed right on it at least once.
- Handled: your last three guesses on it were right. explain then leaves that topic's notes out, until a wrong guess brings them back.
Progress is kept on your machine, in ~/.claude/kotharo/learning/log.jsonl, as metadata only: which lesson, its topic, the step, how it went, the ticket and when. Your guesses, the questions and the answers stay in chat. They never go in handoff.md, a commit, a pull request, a ticket or a close-out record, and a wrong guess never counts as an error in any review. See it with:
kotharo teach progressSet the level
Just for you, in every repo:
/kotharo:config set learning.level coach --userA team profile can set a default for its team, and your own settings win over it. learning.handled_after sets how many right guesses in a row make a topic handled; the default is 3.
Lessons
The core's lessons live in Kotharo's learning/ folder and teach the craft, never anything from your code or your customers. A team profile can add lessons for its own domain in a learning/ folder beside its profile.toml, and kotharo teach check --profile <path to profile.toml> checks them.
Next: Guardrails. All docs