Learnings

A sprint sometimes teaches something: a test that missed a case, a check that agreed with itself, a step that needed a different order. Canon captures that lesson from evidence, queues it, and lets a different reader decide whether it becomes a rule your next session starts with. Nothing is promoted automatically.

See the same flow as a diagram on the Learnings page.

1. Capture at the close

This part happens by itself during sprint complete.

The candidate also shows on the ticket's Learnings tab; see Sprint and gates.

LEARNINGS.md is a queue, not a rulebook. Sessions do not load it, because loading unreviewed lessons into every session would skip the judgment this flow exists for.

2. Judge it later, by someone who was not there

The agent that did the sprint tends to see everything it just did as important, so the flow leaves promotion to a separate, fresh session, which runs /promote-learnings. It reads every UNPROMOTED row and the file behind it, and asks one question of each: is this a class of mistake that a different future sprint would make, or a one-off?

The result is a report. By itself it changes no file.

The Logbook on a project's board shows LEARNINGS.md read-only, with a count of the unpromoted rows, so you can see the queue without a session. Its Promoted tab shows PROMOTED.md and how many of its 60 lines are used. See the Logbook section of Cockpit and board.

3. Promote what you confirm

Register the sprint skill in a project (the + sprint button on its card, or skills.sh add sprint) and canon creates PROMOTED.md at the project root and adds one @PROMOTED.md line to the project's AGENTS.md. Claude Code loads that file at the start of every session.

Run /promote-learnings in an interactive session. After its report it asks which proposals to apply. It writes only the ones you confirm into PROMOTED.md, one or two lines each with the ticket id, and marks each row promoted → PROMOTED.md in LEARNINGS.md. A dismissed row stays in the queue, marked dismissed, and is never loaded.

Because PROMOTED.md loads every time, keep it short. The skill warns when it passes 60 lines.

4. The next session

Open a new session in the project and PROMOTED.md is already in its context, through the import in AGENTS.md. Nobody has to remember the sprint that taught the lesson.

A real example

From a real project: a small ToDo app that uses canon. Every quote below is copied from its files and terminal. Usage meters, a login-expiry line, a plan name and a hover label are blurred in the screenshots, and the column spacing in the two /memory lines is collapsed to single spaces.

1. The reviewer catches it. Sprint t-i9yl built the app. The evaluator passed, and the advisory reviewer said NO, with two findings. The first:

render() rebuilds the whole list via list.replaceChildren() (index.html:40) after every toggle/delete, destroying the focused checkbox/button, so keyboard focus drops to <body> after Space on a checkbox or Enter on Delete

The close wrote this row to LEARNINGS.md:

| 2026-10-02 | [t-i9yl](.tickets/t-i9yl/learnings.md) | Full `replaceChildren()` re-render drops keyboard focus and identical aria-labels hide which task a control acts on (index.html:40,48,53) | UNPROMOTED |

2. A fresh session judges it. In a new Scratch session, /promote-learnings read the row and its source file in full and answered:

Durable: yes. Both are general UI mistakes, not specific to this ticket's code.

Proposed destination: PROMOTED.md. It applies while writing UI code, and a narrower home doesn't exist in a consumer project.

The terminal after typing /promote-learnings: a Promote Learnings Report that read one UNPROMOTED row, judged it durable, proposed PROMOTED.md as its home, drafted the rule, and asks whether to apply it.
The report, with the question it asks next.

It asked:

Do you want me to apply it? Reply "yes" to promote, "dismiss" to dismiss the row, or give edits to the rule text.

The answer was yes.

3. One line is written. PROMOTED.md gained this line and nothing else:

UI lists: after a re-render (replaceChildren/innerHTML) restore keyboard focus to the acted-on control or its neighbor, and give repeated controls per-item aria-labels (e.g. "Delete: <task text>"), not identical ones. (t-i9yl)

The row's status became `promoted → PROMOTED.md`.

4. The next sprint starts with it. A new ticket, "Edit a task in place", with a description that says nothing about focus or labels:

Let me change a task's text after adding it. Double-click the task text to turn it into an input; Enter saves, Escape cancels.

sprint start ran in that ticket's own session. It wrote this in research.md:

PROMOTED.md: restore focus after re-render; per-item aria-labels.

and this among the criteria in acceptance.md:

After save or cancel, keyboard focus lands on that task's checkbox (not body); the edit input has aria-label="Edit task: <task text>" (per PROMOTED.md).

The agent's brief for the Edit a task in place ticket: its approach says the edit input gets an aria-label of Edit task, per PROMOTED.md, and that focus goes to the row's checkbox after save or cancel.
The brief for a ticket whose description never mentioned focus or labels.

/memory in that session lists the file as loaded, @-imported under the project's AGENTS.md:

L /private/tmp/ToDo/AGENTS.md @-imported

· L /private/tmp/ToDo/PROMOTED.md @-imported

The /memory list in the session: user instructions, then the project's AGENTS.md, with PROMOTED.md listed beneath it as @-imported.
PROMOTED.md is loaded through the import in AGENTS.md.

One more route. The project's HANDOFF.md, which sprint start also reads, already listed the same two findings under Next Steps:

Optional: fix the two low a11y findings (focus loss after render, generic aria-labels)

So the new session had two ways to learn about them, and this example cannot separate the effect of PROMOTED.md from that of HANDOFF.md.

What this shows, and what it does not. The promoted line was loaded into the next session through the @PROMOTED.md import, as /memory shows, and the agent's plan cites it ("per PROMOTED.md") and turns it into an acceptance criterion. It does not show that the line was the cause: HANDOFF.md pointed at the same findings, and the only direct sign that PROMOTED.md was used is the agent's own attribution. The session was stopped at the plan, so no evaluator has yet graded whether the built code keeps focus. It is one project and one lesson.

Why not just rely on memory?

Claude Code's own memory and a hand-edited CLAUDE.md carry knowledge between sessions too. They answer a different question.

Item Memory or CLAUDE.md Canon's learnings flow
Who writes it The working agent, from what it recalls or what you said A reviewer and evaluator with no build history find it
Who judges it The same agent that lived through it A separate fresh session, then you
Where it lives Memory: one user's machine. CLAUDE.md: your repository, if you commit it Files in your repository, reviewed like code
It guards against Forgetting a preference or a project fact Repeating a class of engineering mistake

Use memory for how a person works. Use this flow for what the codebase taught you.