Lessons
Lessons turn what a task taught into better guidance for the next one. CoderFlow asks the task's agent what a future task in this environment should know: a correction you had to make, a useful discovery or a step that wasted time. You choose the lessons worth keeping, and Update environment guidance writes them into the environment's instructions, skills or templates.
Lessons are only for people who can edit the environment's guidance (environments:instructions). Nobody else sees a task's Lessons section or Capture lessons.
Capturing lessons is not a follow-up turn or another review of your changes. It does not change the task's approval, conversation or latest response, and it sends no completion notification. Nothing changes the environment until you click Update environment guidance.
Capture Lessons
Nothing runs on its own. Capture lessons in either of two ways:
- When you approve. Tick Capture lessons in the approve dialog. It is never preselected. Lessons are captured in the background after the approval succeeds; this never delays the approval or makes it fail.
- From the task page. Open More actions and choose Capture lessons, or use the button in the Lessons section. The task does not need to be approved first.
The best moment is just before or at approval, while the task's container is still running: CoderFlow can then ask the agent's own session, which is quicker and gives more specific lessons. Wait until the agent finishes its turn. If a new turn starts while lessons are being captured, CoderFlow cancels the capture and discards its answer.
Once lessons have been captured successfully, even if none were found, they cannot be captured again until the task has another follow-up. You can retry a capture that failed or could not start.
Lessons cannot be captured for objectives, judge/review tasks, deploy tasks, test tasks, documentation-publishing tasks, Portal tasks, IBM i import tasks, interactive terminal tasks or environment setup tasks.
How Lessons Are Produced
Normally, CoderFlow asks a read-only copy of the agent's session what it learned. It reads the task's recorded activity instead when the agent has no session that can be copied (Kimi or Bob), the task's container is not running, or the session includes updates about other tasks that are not visible to the same people as this task.
If asking the session fails, CoderFlow tries the recorded activity once in the same run. Recorded activity is not tried when the session attempt ended because a new turn started, the server restarted or the result could not be saved.
The server's Utility AI produces lessons from recorded activity. Its provider and model are selected in Server Settings → Models → Utility AI. Known credential values are redacted from the recorded activity before it is sent, as they are when a person reads the task. For a very long task, Utility AI reads the beginning and the most recent part of the activity. Its lessons can be less specific than a session's.
CoderFlow asks only for lessons that belong in the environment's instructions, a skill or a template. Lessons about the CoderFlow product itself, personal preferences, and facts that belong in a repository's own documentation are left out.
Orchestrated Projects
Lessons for a project's orchestrator task draw on follow-ups and review findings from every other task in the project that is visible to the same people as the orchestrator task. Tasks with different viewers are left out. An orchestrator's approval of a child never captures lessons; Capture lessons on an eligible child still works. See Project Orchestrator.
Review the Lessons
The Lessons section appears once lessons are being captured. When a capture finishes, it shows a short summary of how the task went and each lesson as a rule for a future agent. Open Evidence under a lesson to see where in the task it came from. Already documented means the agent thinks the guidance already exists; check that claim before using it.
| Action | What it does |
|---|---|
| Use | Chooses the lesson for Update environment guidance. It does not change any guidance yet. |
| Dismiss | Marks the lesson as not worth keeping. |
| Undo | Returns a chosen or dismissed lesson to undecided. |
After a decision, the section shows who made it and when. Decisions are unavailable while lessons are being captured.
Update Environment Guidance
Click Update environment guidance to apply the lessons you chose with Use. It starts an ordinary task in this environment, as you, private to you. The task:
- reads the current instructions, skills and templates first, merges duplicates and skips what is already covered;
- edits only the environment's instructions, skills and templates, through the shipped Environment Instructions, Skill Editor and Environment Templates skills, using your own permissions;
- never writes memory or edits repository files, and cannot create, control, land or deploy other tasks;
- reports what it did with each lesson.
Starting it needs environments:instructions and permission to create a task in the environment. Each edit also needs the permission for its destination: environments:templates for templates, and skills:task-edit with environments:skills for environment-owned skills.
While the task works, its lessons show Being applied to the environment's guidance and cannot be changed, and the section links to the task. Only one such task runs for a task's lessons at a time. When its turn ends:
- a lesson it put into the guidance shows Applied to the environment's guidance;
- a lesson the guidance already covered shows Already covered by the environment's guidance;
- a lesson it could not place stays chosen, so you can try again, Dismiss it or handle it yourself; the task's result says why.
Use Open the task to read its result. Edits through these skills take effect when saved; review them in the setup repository's uncommitted changes before publishing them through the configuration workflow.
Earlier Lessons After Another Capture
While lessons are being captured again, and if that fails or cannot start, the previous lessons remain, including undecided ones. A successful capture replaces the previous undecided lessons and carries forward up to 30 chosen, dismissed or applied lessons after the new ones. The section uses Earlier lessons when the latest capture is still running, failed, could not start or found nothing new.
Understand the Section's Status
| Message | Meaning |
|---|---|
| “Capturing lessons. They appear here when it finishes.” | Wait for the answer before deciding on lessons. |
| “No lessons from this task.” | The capture finished and found no lessons. |
| “No new lessons from this task.” | It found nothing new; earlier decisions are still shown. |
| “Nothing left to review.” | Every lesson has been chosen, dismissed or applied. |
| “Capturing lessons did not finish.” | It started but did not produce a usable saved answer. The section explains why. |
| “Lessons could not be captured.” | The attempt could not start. The section explains why. |
A capture may not finish because it took too long, the agent had an error, its answer could not be read as lessons, a new turn started, the server restarted or the result could not be saved. A session's answer is also discarded if, by the time it finishes, the session includes updates about other tasks that are no longer visible to the same people as this task.
Use Capture lessons in the section to retry when it is available.
| Situation | What to do |
|---|---|
| “Utility AI is not available.” | Ask an administrator to set up Utility AI, then retry. |
| “The task's transcript is not available.” | Ask an administrator to check the task's activity record. Retry once a usable record is available. |
| The agent's session is not ready | Wait for the session to be ready and any running turn to finish, then retry. |
| A rewind or provider switch is waiting for a follow-up | Continue the task with the follow-up, let its turn finish, then retry. |
| A fork has not started its own session | Let the fork start and finish its first turn, then retry. |
| Another operation on the task is in progress | Wait for it to finish, then retry. |
| “A new turn started, so it was cancelled.” | Let the new turn finish, then capture lessons again. |
| The capture timed out, the agent had an error or the server restarted | Retry once the task is idle and the service is available. If the problem continues, ask an administrator. |
| The result could not be saved | Ask an administrator to check storage before retrying. |
Access and Privacy
Reading a task's lessons needs environments:instructions on its environment as well as access to the task's content; people who see a task only through a view-only share never see its lessons. Capturing lessons, Use, Dismiss and Undo also need tasks:execute and the task's ownership checks. See lesson permissions.
The person who captures lessons must still have access when the session copy or Utility AI starts; the resulting lessons are stored for everyone who may read them, even if that person loses access meanwhile.
When recorded activity is used, it is sent to the server's Utility AI provider with known credential values redacted. This can be a different provider and account from the task's agent.
Usage and Limits
Asking the session uses the task's agent account; reading recorded activity uses the server's Utility AI account. A capture uses at most one session copy and one Utility AI call. It can read a large conversation, so usage depends on that context and the provider's caching; it is cheapest while the task's session is recent. Because nothing runs on its own, lessons cost nothing until someone captures them.
Asking the session has a four-minute limit; the Utility AI call has a two-minute limit. A capture returns at most seven new lessons. Update environment guidance is an ordinary task and uses the task agent's usage like any other.
Long text is shortened with an ellipsis: the summary and each rule are limited to 600 characters, and evidence to 1,000. Added evidence from follow-ups and reviews is limited to 24,000 characters in total and 2,000 per item, keeping the newest first. Credentials are redacted from the summary and lesson text before they are stored.