# Learn

> 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.

- Skill: `theplenkov/learn` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add theplenkov/learn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/learn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/theplenkov/learn

---


# /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.

