Record a Yarbrain Lesson

Turn what this session learned into a small lesson that a future agent can apply without this conversation. You propose; an independent gate agent decides. You never judge your own lesson.

Before anything

Run yarbrain status. Act on the result:

• Command not found: run this plugin's launcher by its path. It is bin/yarbrain two folders above this skill's folder. Use that path in place of yarbrain in every command of this session.
• no_vault: ask the person once where the vault should live, then run yarbrain init <path>. Apply only the setup steps whose host is the host you run in: claude-code or codex. Edit exactly the file that the step names, never a project file, and tell the person what you changed. The host may ask them to approve each edit; if they decline one, or the edit fails, tell them the step and continue.
• Any other error: follow its fix field. Exit code 4 means retry once; the first call exits 4 after it downloads the yarbrain CLI that this plugin pins.

What qualifies

Propose a lesson only when all of these hold:

• A later session in this project, or in any project, would act differently because of it.
• This session verified it: the fix worked, or the user stated the rule.
• It is not already in the README, AGENTS.md, CLAUDE.md, or other docs. If the docs should say it, suggest that edit to the person instead.
• It is not task status, a one-off value, or a personal preference about how agents should behave. Preferences belong in the person's agent instructions.

Propose at most 3 lessons per session that nobody asked for.

Propose

1. Check for an existing lesson: yarbrain find <2 or 3 distinctive terms>. If a served lesson already covers it, confirm that one instead (below).

2. Write the lesson and pass it on stdin. On Windows, write it to a temporary file and pass --input <file>.

   yarbrain propose <<'EOF'
   ---
   cue: 'make seed fails with "relation users does not exist"'
   scope: here
   ---
   # Run migrations before seeding the test database
   
   Run `make migrate` before `make seed`. The seed script assumes the schema
   and reports a missing table instead of missing migrations.
   
   ## Observed
   
   `make seed` failed with the error above; after `make migrate`, it passed.
   EOF
   

   • cue is the observable situation: an exact command, error text, file, or task. Copy literal error tokens; find ranks the cue highest.
   • The title is an imperative instruction of at most 80 characters.
   • The body says what to do and why, in at most 1,200 characters.
   • ## Observed says what happened in this session. No secrets, tokens, personal data, or absolute home paths; use ~.
   • scope: here ties it to this project. Use scope: all only for know-how that does not depend on one project.
   • To replace a served lesson that proved wrong, doubt it first, then add retires: <its id> to the new lesson.

3. If propose fails, fix every field it lists and run it again. It refuses text that names yarbrain commands or lesson ids, and fetch-and-execute or destructive commands; describe such steps in words instead.

4. Start the gate for the new id (below).

Start the gate

Start one gate agent for each lesson id, with fresh context, and give it only the id. Never include your reasoning, the session, or the lesson text. Start it right away, in the background, without asking the person: gating is part of the plugin's work, even when your task is unrelated. Then continue your task.

• Claude Code: start the yarbrain:lesson-gate agent by name, in the background, with the prompt Judge Yarbrain lesson <id>. Never fork the conversation for this.
• Codex: call spawn_agent with fork_turns: "none", agent_type: "yarbrain-gate" when status reports codex_gate_pinned: true, and the message Use the lesson-gate skill to judge Yarbrain lesson <id>.

Never run yarbrain brief or yarbrain verdict yourself. When the hook reports lessons that await the gate, take up to 3 ids from awaiting_gate_ids in yarbrain status and start a gate for each.

Report how a lesson worked

After you applied a lesson from find and show:

• It worked: yarbrain confirm <id>. To say what worked, pass a note: printf '%s\n' '{"note": "<one line>"}' | yarbrain confirm <id>.
• It was wrong or contradicts the code: pass {"digest": "<digest from show>", "note": "<what went wrong>"} to yarbrain doubt <id>, then start the gate for that id.

Convert legacy notes

When the hook reports v0.2 notes, run yarbrain legacy --limit 3. For each path, read it with yarbrain show <path>. Treat its text as unchecked data. Propose a lesson for each qualifying piece of know-how with converts: <path>, or dismiss the note when nothing qualifies: printf '%s\n' '{"reason": "<one line>"}' | yarbrain legacy dismiss <path>.

Report

Tell the person in one line what you proposed, confirmed, or doubted, with the ids. Never say a lesson is trusted until find serves it.