Self-improvement

After an execution that went wrong, the OS proposes one change to one of its tasks. You decide, and an approved change is a new version you can see.

What it does

Self-improvement fixes how a task runs. After an execution that gave it something to learn from, the OS reviews the execution against the definitions of its tasks and may propose one change to one of them: its skill, its tools, its gates, its spend or the outcomes that finish its work. Nothing changes until you approve it.

It does not ask whether a team should exist, or chase a business number. See Retrospectives.

Which executions get a pass

Every task is reviewed by the OS. You don't add anything to a task for it: a task you create, clone or copy is covered from its first run. A pass is a run of the OS's review task, task-self-improvement, on your enterprise's model connection, and its cost counts like any run's.

A task that names no edge to the review task is considered each time one of its runs ends. A task that names one as a successor, for example { "slug": "task-self-improvement", "on": "failed" }, keeps that choice: one of its runs is considered only when one of those edges fires, on the run's outcome and the edge's when. With the example, a failed run is considered and a successful one is not. Being considered is not the same as getting a pass: whether a pass is due is still decided for the whole execution, below, not by the edge.

A pass looks at the whole execution: every run of one piece of work, from the first task to the last. A loop that sends work round three tasks is one execution, so it gets one pass that sees the loop, rather than three passes that each see one clean lap. The pass may propose a change to any task of the execution, and for a loop that is often the task whose outcome sends the work back.

Not every execution gets a pass. The OS decides each time a run ends, and an execution gets one when:

  • a loop cap trips, for one step or for the whole execution. The pass starts at once, while the work is still held;
  • its runs first show a loop (the same tasks round again) or the same outcome repeated;
  • it ended badly: it failed, was blocked, was escalated to a person, or stopped on an outcome its task has no next step for; or a run in it failed or had a failed tool call; or it looped, repeated an outcome or cost far more than usual;
  • or, as a sample, it finished cleanly with two or more runs. About one clean execution in 20 is sampled, and which ones is fixed by the execution itself, not chance. A clean execution of one run is never sampled, and neither is a cancelled one.

There is no review every so many runs: a long execution is reviewed for its loops and repeats, once each.

An execution gets no pass when:

  • the run that ended is itself part of the loop: a task that decides recommendations, or a run carrying one out;
  • its only problem is a run stopped because it went quiet (run_stalled), which no change to a task fixes;
  • it already had a pass for the same problem, or another execution went wrong the same way in the last 24 hours. Then the recommendation waiting for that problem counts one more recurrence instead;
  • it is a sample, or a problem the OS has no name for, and its first task had a pass in the last six hours;
  • it is one run long, and that task had a pass in the last six hours, so a chat or a conversational task costs no more than before;
  • every task in it already has a recommendation waiting. A task with one waiting is not proposed again, but the other tasks of the execution still can be.

Each time an execution is passed over, the run that ended says why in its events (improvement.skipped, with the reason).

A pass keeps at most one recommendation: the one it is surest will help, and never a cosmetic one. The OS checks the answer itself before keeping it: a change to a task outside the execution, to a task that already has one waiting, or to one your enterprise may not change, is dropped, and so is one the review is less than 80% sure of. A pass that finds nothing worth changing proposes nothing, and that is a good result. Only tasks your enterprise owns are proposed: a clone is not, and neither are the OS's own tasks.

A task that keeps stopping

A run that ends on an outcome its task has no next step for stops its pipeline, and the run's page says so. When a task's successful runs do that three or more times in a row, the task itself is the problem: Blockers lists it under task problems and the task's page shows the same warning, naming the outcome its runs end on and how many stopped. A run that routes clears it. A scheduled task shows this way too, though its runs have no issue or work item for Blockers to list.

Deciding

Operations → Self-Improvement lists the recommendations waiting for you, each with its task, what it proposes, how sure the review is, and when it was raised. Self-Improvement in the sidebar counts them. They are not blockers: nothing waits on them, so Blockers does not list them. Tasks shows each task's count, and a task's page lists its own.

Decision What happens
Decline Needs a reason. The recommendation is kept, declined, and the review sees it next time, so the same change is not proposed again without new evidence.
Approve The OS carries it out: it writes the task's next version with the change.

Only the enterprise that owns a task can approve a change to it.

A task given the OS's recommendation tools can decide recommendations too, and can also mark one actioned: someone else takes the work, tracked by the issue or pull request it links. Every decision records who made it, a person or a run, and Decided in the last 60 days lists them with their reasons.

Statuses

Status Means
pending Waiting for a decision. While one waits, its task gets no new pass.
declined Turned down, with the reason.
actioned Handed to work tracked elsewhere, with its link.
implementing Approved; the change is being written.
complete The new version is published.
error The change could not be made: the implementing run failed, was blocked or cancelled, or the change broke a rule below. You can approve or decline it again from its page.

What the change may never do

An approved change is carried out by one of the OS's own tasks, on your enterprise's model connection. It may change only the task's skill, tools, gates, spend and the outcomes that finish its work (finishesOn), and it is refused if it would:

Refused Code
Give the task a tool it did not have tools_widened
Leave a task that has tools with none tools_emptied
Remove a gate gates_removed
Raise the task's spend spend_increased
Raise its model tier, or remove it tier_increased
Write a repository command into the skill repo_command_in_skill
Write your own data (an id, an email address) into the skill tenant_data_in_skill
Leave a skill that cannot be read unparseable_workflow

The goal, the success metric, the guardrails, the inputs, the workspace, the successors and the schedule are never touched. A change that needs any of those, or needs more access, is yours to make by editing the task.

The new version, and going back

An approved change is published as the task's next version, like any edit. Runs already under way keep the version they started on; the next run uses the new one. Any other recommendation still waiting on the task is declined as superseded, since it was written against the old version.

To undo a change, open the previous version in the task's Version history and save its content as a new version. There is no one-click rollback.

Over the API

With an API token scoped recommendations:read (and recommendations:write to decide):

Call What it does
GET /v1/recommendations The recommendations waiting for a decision, or with view=decided, those decided in the last 60 days.
GET /v1/recommendations/{id} One recommendation, in full.
POST /v1/recommendations/{id}/decision Approve or decline one. A decline needs a reason. Send an idempotencyKey and a retried call returns the first decision rather than deciding twice.