/learn (bro)
All mechanics live in the bro CLI. This skill is policy only —
matching, injection, and dedup live in @broject/learn and the hooks
layer.
Prereq: bro on PATH or npx -y @broject/bro@0. Requires bd — lessons
persist as bd kv entries under the learn/ prefix, synced with the
beads store.
What a lesson is
One durable unit of agent knowledge: a rule plus the trigger that
decides when it surfaces (hook events + context conditions — terms,
commands, paths, tools, errors). Match keys are optional and conjunctive:
a trigger with --on alone is a valid event-scoped lesson that fires on
every configured hook event — match keys just narrow it. Injection is
capped by budget per session and learn.maxInject per probe.
| Command |
What it does |
bro self learn add --lesson "…" --on E… --evidence K:R… |
Store a manual lesson — --on and ≥1 --evidence required, both repeatable (kinds: bead, pr, session, command, text) |
bro self learn list [--json] [--source X] [--confidence X] |
List lessons |
bro self learn show <id> |
One lesson as JSON |
bro self learn forget <id> |
Delete a lesson |
bro self learn promote <id> |
Graduate a lesson to a rule-edit bead — carries the rule, trigger, and evidence; the lesson records promotedTo and keeps firing until the rule lands |
bro self learn capture [--source drill|retro|act|mol|all] [--mol ID] [--dry-run] |
Distill finished artifacts (drill memos, retro beads, review findings, mol results) into trigger-shaped lessons |
bro self learn probe <question> |
Store-first query — a hit prints ranked lessons; a miss prints candidates and logs the gap. --lesson "…" stores the distilled answer (phase 2 — needs a trigger: --on/--match-* or a question with usable terms) |
Policy
- Evidence is required, not decorative. A lesson that cannot cite
where it was learned is not storable —
--evidence names the bead, PR,
session, command, or literal text. Confidence derives from it:
tentative → established on ≥2 independent evidences — or a single one
where the lesson already held under a real gate (the PR it warned
about merged green, the prevention it stated closed the retro).
learn for conditioned knowledge, bd remember for context-free.
"Repo uses native TS" is a memory — it injects always. "When running
gh pr merge, sweep debt" is a lesson — it fires only at the trigger.
Storing a conditioned lesson as a memory recreates the AGENTS.md
always-on problem in a new place.
- Probe before you re-investigate. A question the store already
answered short-circuits for free — but a hit is a ranked guess: one
shared term can surface an unrelated lesson, so check it actually
answers the question before skipping the investigation. On a real
miss, finish the work and store the answer via
probe --lesson —
a later session whose context matches the trigger gets it for free.
- Capture at artifact close, dry-run first.
capture --dry-run
renders the would-be lessons without writing — capture is a proposal
surface. Re-capturing merges evidence and recomputes confidence
instead of duplicating.
- Write triggers that can fire. A lesson whose match keys never
hit is dead weight. Prefer
prompt-submit terms for human-driven
triggers, post-tool commands/paths for workflow triggers — and keep
budget at 1 unless repetition is the point.
- Recurrence means promotion. A lesson that keeps firing on the
same mistake is asking to become a rule — the fix lands in the skill,
AGENTS.md, or rules file via the normal spec/PR path, not by editing
the lesson forever.
1---23name: learn4description: "Use when a lesson should outlive the session — 'remember this for next time', capturing a drill/retro/review finding, or asking whether the store already knows the answer. Thin wrapper over the bro CLI: `bro self learn` is the lesson store; the learn connector injects matched lessons at session-start, prompt-submit, and post-tool. Requires `bro` (npx -y @broject/bro@0) and bd."5metadata:6 source: https://skillmd.com/skills/theplenkov/learn7---89# /learn (bro)1011**All mechanics live in the `bro` CLI.** This skill is policy only —12matching, injection, and dedup live in `@broject/learn` and the hooks13layer.1415Prereq: `bro` on PATH or `npx -y @broject/bro@0`. Requires `bd` — lessons16persist as `bd kv` entries under the `learn/` prefix, synced with the17beads store.1819## What a lesson is2021One durable unit of agent knowledge: a rule plus the **trigger** that22decides when it surfaces (hook events + context conditions — terms,23commands, paths, tools, errors). Match keys are optional and conjunctive:24a trigger with `--on` alone is a valid event-scoped lesson that fires on25every configured hook event — match keys just narrow it. Injection is26capped by `budget` per session and `learn.maxInject` per probe.2728| Command | What it does |29| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |30| `bro self learn add --lesson "…" --on E… --evidence K:R…` | Store a manual lesson — `--on` and ≥1 `--evidence` required, both repeatable (kinds: bead, pr, session, command, text) |31| `bro self learn list [--json] [--source X] [--confidence X]` | List lessons |32| `bro self learn show <id>` | One lesson as JSON |33| `bro self learn forget <id>` | Delete a lesson |34| `bro self learn promote <id>` | Graduate a lesson to a rule-edit bead — carries the rule, trigger, and evidence; the lesson records `promotedTo` and keeps firing until the rule lands |35| `bro self learn capture [--source drill\|retro\|act\|mol\|all] [--mol ID] [--dry-run]` | Distill finished artifacts (drill memos, retro beads, review findings, mol results) into trigger-shaped lessons |36| `bro self learn probe <question>` | Store-first query — a hit prints ranked lessons; a miss prints candidates and logs the gap. `--lesson "…"` stores the distilled answer (phase 2 — needs a trigger: `--on`/`--match-*` or a question with usable terms) |3738## Policy3940- **Evidence is required, not decorative.** A lesson that cannot cite41 where it was learned is not storable — `--evidence` names the bead, PR,42 session, command, or literal text. Confidence derives from it:43 tentative → established on ≥2 independent evidences — or a single one44 where the lesson already held under a real gate (the PR it warned45 about merged green, the prevention it stated closed the retro).46- **`learn` for conditioned knowledge, `bd remember` for context-free.**47 "Repo uses native TS" is a memory — it injects always. "When running48 `gh pr merge`, sweep debt" is a lesson — it fires only at the trigger.49 Storing a conditioned lesson as a memory recreates the AGENTS.md50 always-on problem in a new place.51- **Probe before you re-investigate.** A question the store already52 answered short-circuits for free — but a hit is a ranked guess: one53 shared term can surface an unrelated lesson, so check it actually54 answers the question before skipping the investigation. On a real55 miss, finish the work and store the answer via `probe --lesson` —56 a later session whose context matches the trigger gets it for free.57- **Capture at artifact close, dry-run first.** `capture --dry-run`58 renders the would-be lessons without writing — capture is a proposal59 surface. Re-capturing merges evidence and recomputes confidence60 instead of duplicating.61- **Write triggers that can fire.** A lesson whose match keys never62 hit is dead weight. Prefer `prompt-submit` terms for human-driven63 triggers, `post-tool` commands/paths for workflow triggers — and keep64 `budget` at 1 unless repetition is the point.65- **Recurrence means promotion.** A lesson that keeps firing on the66 same mistake is asking to become a rule — the fix lands in the skill,67 AGENTS.md, or rules file via the normal spec/PR path, not by editing68 the lesson forever.