learn

Record a learning

Save a durable, evidenced lesson for future runs on this repo/task via the octomux learn CLI. There is no per-add human gate — what you write here goes straight into the pool that gets seeded into future prompts, so the bar is on you.

When to use

• You just fixed something that wasn't obvious from the code alone (a flaky mock, a required env var, a gotcha in a build step, a convention you only found by trial and error).
• You're about to end your turn and you have context (your reasoning, not just the outcome) that the transcript will not carry forward — the next fresh-context iteration only sees the prompt, not your chain of thought.

The schema

octomux learn --trigger "<when this applies>" --lesson "<the durable fact or action>" \
  --evidence "<file / command / error that proves it>" [--private]

• --trigger — the situation this applies to (so a future run knows when to recall it).
• --lesson — the durable fact or action itself. State it as something actionable, not a vague reminder.
• --evidence — the file path, command, or error text that backs it up. No evidence, no save — if you can't point at something concrete, it isn't a learning yet, it's a guess.
• --private — use for a quirk specific to this job (a one-off env, a task-specific workaround). Omit it (shared, repo-general) for anything a different task in this repo would also benefit from.

The bar: save the why, not just the what

The transcript is gone once your context resets. The lesson is your only chance to hand your reasoning forward — write it like you're leaving a note for an agent with none of your context.

Good (durable, evidenced, actionable):

• "When bun test hangs on launch.test.ts, the fs mock needs default: mocked — server/task-engine/setup"
• "The hedging retry lives in server/retry.ts; jitter was missing and caused thundering-herd retries under load — server/retry.ts:42"

Bad (vague, no evidence, not a lesson):