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.
tkt learnwrites.tickets/<id>/learnings.mdfrom the sprint's deviations from its plan, the evaluator's findings and the reviewer's findings. The file is markedUNPROMOTED. A clean sprint, with no deviations and no findings, writes nothing.learnings-sweepadds one row for the ticket to theLEARNINGS.mdfile at your project's root: newest first,UNPROMOTED, linked to the ticket's file. It is a step the agent follows, written in a skill. It is not a command, a hook or a close gate, so it never blocks a close.
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?
- For a lesson that will last, it proposes exactly one place for it.
- For a one-off, it recommends dismissing it, with a one-line reason.
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 vialist.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.

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 hasaria-label="Edit task: <task text>"(per PROMOTED.md).

/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

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.