| name | workflow-improver |
| description | The outer loop: reads a bounded window of the workflow's own run exhaust — gate logs, route-back reasons, reconcile reports (NOT memory rows - see below) reports — clusters the shapes that RECUR, and proposes at most three `skill-amendment@1` records naming the target skill, the target passage, the quoted evidence with its ids, and the change. Runs `docs-tools/workflow-improve.mjs` as its machine floor. Every proposal lands as a `status: draft` task via create-tasks and is never self-audited to ready_to_implement. It PROPOSES; it never edits — it writes to no `modules/**` path, no SKILL.md, no rubric, no workflow file. A window with no recurring pattern reports "no amendment proposed" and emits nothing. Use when asked why the workflows never learn, or to mine the last N completed tasks for corrections the operator has already made by hand. Do NOT use to review a consumer repo's product code — this reads OUR loop's exhaust, not a codebase. |
| skill_version | 1.0.0 |
| artefact | skill-amendment@1 |
| tool | docs-tools/workflow-improve.mjs |
| hitl | required |
| untrusted_inputs | {"wrap_in_marker":"untrusted_content","injection_scan":"required","on_marker_hit":"surface_to_human"} |
workflow-improver — propose skill amendments from run evidence
Why this exists
Every ingredient of a learning loop is already on disk and nothing reads it back. Human verdicts at two gates, routed_back_count, route-back reasons rows, retrospectives, reconcile reports: all written down, none consumed. So an external reviewer found the same defect class in three consecutive rounds and a human spotted the pattern, not the system. Every correction an operator makes ("drop section 4", "gate depends_on") lives in a gate log, not in a skill. The next run re-derives it or does not.
This skill closes that loop by exactly one notch: it turns recurring evidence into a proposal a human reads. It does not turn evidence into doctrine.
The hard rule
It proposes; it never edits. No write to modules/**, no SKILL.md, no rubric, no workflow file — not behind a confidence threshold, not for a "small" change. The tool refuses such an --out before it reads anything, and the agent MUST NOT hand-apply what the tool proposed. Our doctrine is that a human accepts every change, and a skill edit is a doctrine change. The article's design opens a PR against the skill; ours opens a task.
An unreviewed amendment to a skill is worse than no amendment: it is doctrine nobody agreed to, and nobody knows it happened.
Machine floor first
Run the tool BEFORE forming any opinion:
node .cyberos/docs-tools/workflow-improve.mjs --window 20
It is read-only over the corpus (its only write path is --out, and that path is confined and refused into every doctrine tree). It emits improvement-window@1: the window it read, every evidence row with a stable id, the clusters, and at most three skill-amendment@1 proposals. The mechanical half is the tool's and the model does not re-derive it:
| Step | What the tool decides |
|---|
| Window | the last N status: done tasks (default 20), ordered by shipped (falling back to created_at) — the recorded completion date, NOT the task number. Ordering by number put TASK-CUO-301 above every TASK-IMP-1xx and produced a window containing none of the run's own tasks: 20 read, 0 evidence, indistinguishable from a clean window. The tool reports which key it used per task (order_source). |
| Readers | route-back cells; each task's and |
