Retrospectives
A retrospective captures lessons from a task. The Lessons card shows suggestions you can keep or skip, with evidence from the task. Use it to capture a correction, a useful discovery or a step that wasted time.
It 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 it produces changes memory, instructions, skills or templates on its own.
Run a Retrospective
After a person approves an eligible task, CoderFlow can run a retrospective in the background. The environment's Retrospectives setting controls whether this happens; it is Off by default. A retrospective never delays approval or makes it fail. Approvals made by another task or an automation do not trigger one.
To start one yourself, open More actions on the task page and choose Run retrospective. You can run it on an eligible task whose agent has finished its turn; the task does not need to be approved first. The same button is available on the Lessons card when another run can start. Manual runs work in every environment mode, including Off.
Wait until the agent finishes its turn. Only one retrospective can run on a task at a time. If a new turn starts during the retrospective, CoderFlow cancels it and discards that answer.
A completed retrospective, even one with no lessons, cannot run again until the task has another follow-up. You can retry a retrospective that failed or could not start with Run retrospective when it is available. Automatic runs do not retry a failed run unless the task has another follow-up.
Retrospectives are never available 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. This is the same activity people who can view the task can read.
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. For a session that is not ready, a pending rewind or provider switch, a forked task that has not started its first session, or another operation in progress, see the What to do table.
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, not all of it. Its lessons can be less specific than a session's because the activity record can be shortened and Utility AI cannot ask the agent itself. The Lessons card does not say which source was used.
Orchestrated Projects
A project's retrospective draws on follow-ups and review findings from every other task in the project that is visible to the same people as the orchestrator task. This applies whether it starts after a person's approval under the environment's setting or through Run retrospective on the orchestrator task. Tasks with different viewers are left out. Children approved by the orchestrator do not get their own automatic retrospective; Run retrospective on an eligible child still works. See Project Orchestrator.
Review the Lessons
The Lessons card appears when a retrospective starts, or when an automatic run could not start. When it finishes successfully, the card shows a short summary of how the task went. Each lesson shows a suggested rule, its evidence, its kind, its suggested home and confidence. A home is the retrospective's suggestion of where the rule belongs, such as an instruction section, a skill, a template, memory or repository documentation. Keeping a lesson does not change any guidance, and Apply accepted lessons can update only the environment's instructions, skills or templates, never memory or repository files. Already documented means the retrospective suggests the guidance already exists; check that claim before keeping it.
| Action | What it does |
|---|---|
| Keep | Copies the lesson into the environment's Lessons list as a proposal for someone to review. It does not change the environment's guidance. |
| Skip | Marks the lesson as skipped. |
| Undo | Returns a kept or skipped lesson to undecided. If its environment proposal is still waiting for a decision, that proposal is removed. |
Once someone has accepted, rejected or applied a proposal in the environment, you cannot change that lesson's decision from the task card. Decisions are also unavailable while a retrospective is running. After a decision, the card shows who kept or skipped the lesson and when.
Lessons labelled Product feedback have no environment home. Use Copy to copy the rule and its evidence, or Skip to dismiss it. Product feedback cannot be kept in the environment's list and does not count as a lesson waiting for your decision.
On the dashboard, a Lessons pill shows how many lessons still need a decision across the tasks in that tile. Open the task to keep or skip them.
Kept lessons continue in the environment's Lessons tab, where a person decides which proposals to accept.
Earlier Lessons After Another Run
While another retrospective runs, and if it fails or cannot start, the previous lessons remain, including ones you have not decided on. A successful run replaces the previous undecided lessons and carries forward up to 30 kept or skipped lessons after the new ones. This also happens when the new run finds no lessons.
Lessons from before the task's latest follow-up are labelled From an earlier retrospective. The card uses Earlier lessons when the latest run is still running, failed, could not start or found no new lessons. A proposal already sent to the environment keeps the text it had when you chose Keep.
Understand the Card's Status
| Message | Meaning |
|---|---|
| “A retrospective is running. Lessons appear here when it finishes.” | Wait for the answer before deciding on lessons. |
| “No lessons from this task.” | The retrospective finished and found no lessons. |
| “No new lessons from this task.” | It found nothing new; earlier decisions are still shown. |
| “Nothing left to review.” | No ordinary lessons are waiting for Keep or Skip. Product feedback may still be present. |
| “The retrospective did not finish.” | It started but did not produce a usable saved answer. The card explains why. |
| “The retrospective could not start.” | The attempt could not start. The card explains why. |
After a failed session attempt, CoderFlow tries recorded activity except in the cases listed in How Lessons Are Produced. The card shows the result of that second attempt, even if it could not start.
A run 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. For either source, an answer is also discarded if a project task or review whose follow-ups or findings were used stops being visible to the same people during the run.
When recorded activity cannot be used, the card says “The retrospective could not start.” with “Utility AI is not available.” if Utility AI is not set up, or “The task's transcript is not available.” if the task has no usable activity record.
Use Run retrospective on the card 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. The next approval by a person can start a fresh retrospective under the environment's setting; you can also run one manually. |
| The run 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
People who can view the task's content can see its lessons. People who can see a task only through a view-only share do not see its lessons. Running a retrospective and choosing Keep, Skip or Undo also require tasks:execute and the task's ownership checks. Permission to send follow-ups alone is not enough. Copy needs only access to the lesson you can already read.
The person who approves or clicks Run retrospective must still have access when the session copy or Utility AI starts; the resulting lessons are stored for everyone who can view the task's content, even if that person loses access meanwhile.
When recorded activity is used, known credential values are redacted from it before it is sent to the server's Utility AI provider, as they are when a person reads the task. This can be a different provider and account from the task's agent.
Keeping a lesson shares its text and evidence with people who can open the environment's Lessons tab, even if they cannot open the source task. They see the source task's name and link only when they have access to it. See retrospective permissions.
Usage and Limits
A retrospective that asks the session uses the task's agent account; one that reads recorded activity uses the server's Utility AI account. A run 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. Enabling automatic retrospectives adds this usage after eligible approvals; leaving the setting Off adds none automatically.
Each eligible approval can start one bounded run; after a completed result, another run needs a new follow-up. Asking the session has a four-minute limit; the Utility AI call has a two-minute limit. A run returns at most seven new lessons. A manual retry is another run.
A very long Utility AI answer can be cut off; the card then says “The retrospective did not finish.” and earlier lessons stay.
Long text is shortened with an ellipsis: the summary and each rule are limited to 600 characters, evidence to 1,000, and the home detail to 200. Added evidence from follow-ups and reviews is limited to 24,000 characters in total and 2,000 per item, keeping the newest first. These limits mean a retrospective may not cover every detail of a long task. Credentials are redacted from the summary and lesson text before they are stored.