workflow-improver

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