improve

name	improve
version	3.19.0
description	The improvement skill. Understand the ask, examine the target, challenge the first read, decide on one change (or argue for redesign, or declare silence), honor the operator's supervision or delegation boundary, act, reflect, record, and report the result clearly. USE WHEN: improve, audit, review, fix, refactor, redesign, evaluate, what would make this better, am I missing something.
argument-hint	The target to improve, and optionally the concern (correctness, simplicity, performance, etc.)

Improve

Understand. Examine. Challenge. Decide. Act. Reflect. Record. Or argue convincingly that nothing should change.

ACM role: Reads the governing current surfaces and relevant evidence before every run; extends the memory layer with each iteration's findings.

This is the suite's single entry point for normal work. The operator invokes Improve; Improve applies Intent and Trail every run, and schedules Destination and Orient only when their evidence-based triggers fire. It combines what v2 split into Kaizen (incremental), Kaikaku (radical), and Hansei (reflection) — because in practice the agent should pick which mode the situation calls for, not be told.

Lineage: Kaizen and Kaikaku both trace to PDCA (Plan-Do-Check-Act, Deming/Toyota) and Boyd's OODA loop — cited explicitly in this skill's own v1 ancestor but dropped when v2's three skills merged into this one. Restored here rather than left implicit.

Governing principles

This skill exists to enact three principles:

1. Operator's Intent — what + why, not how. You are given a destination, not a route. The lenses below are vocabulary for thinking, not a checklist to execute.
2. Observable Autonomy — every reasoning step is recorded as it happens. If an observer can't reconstruct what you did and why from the trail alone, the work is invisible regardless of how good it was.
3. Convergence Is Silence — finding nothing actionable is a valid outcome and advances the system toward done. Do not manufacture findings to justify the run.

Full statement of the principles: PRINCIPLES.md — read it if available, but this skill operates fully without it.

The work

1. Understand the target and the ask

Apply Intent automatically now. Intent is an ingress service of the full suite, not a command the operator must remember to invoke. Do not ask the operator to run it separately. Continue to step 2 when done.

Tell the operator what is happening in one useful sentence: Intent is interpreting this prompt as the mandate for the current run, then will honor the explicit supervision or delegation boundary before Improve continues. A repository-level .acm/destination.md is not required for the first run. When no durable Destination exists, the confirmed interpretation, current conversation, and target evidence govern this iteration.

If this is a standalone Improve installation and Intent is unavailable: before examining anything, narrate your interpretation of what you've been asked to do, in your own words. State what you believe the destination is and what would count as success. If your interpretation diverges from a literal reading of the request, say so explicitly so the operator can correct course before you act.

If the ask is about convergence or publication readiness, read the repo's convergence-scope protocol before proceeding if it has one, then declare which layer (problem, principles, skills, cross-layer coherence) this run is evaluating.

Before examining the target, check the target repo's .acm/ folder for orientation files and read whichever exist, in this order. The .acm/ folder is always in the root of the repo being worked on — never in the skills install directory.

ACM §4 Scoped Memory — read parent scopes first. Before reading the repo's own .acm/, traverse parent directories upward and read any .acm/destination.md found there. Higher-scope mandates govern lower-scope ones — if a workspace or org destination conflicts with the repo destination, the higher scope wins. Label each scope when reading (e.g., "workspace mandate", "repo mandate"). Stop traversal when any of: filesystem root reached; a .acm-root marker file is found in a directory (operator-declared ceiling — read that directory's .acm/ then stop); or 4 levels traversed (implementation ceiling).

1. .acm/destination.md — the operator-held destination. What the target is for, the constraints that hold across all runs, the hard problem the work is trying to chip away at. Stable: not written by any skill, only by the operator/team. If present, it is the highest-priority context — it tells you what success means before you decide what to change.
2. .acm/orientation.md — the current Orient-derived orientation and operational rules. What the arc currently shows is true of the target, and critically, the Active operational rules you must obey. Rewritten each Orient run. You must actively anchor your runtime behavior to any lessons learned recorded here (e.g., if it says "Always use pure functions here", you must comply).
3. .acm/learning.md — the compact learning surface if present. A derived chronological extract of the most recent [!REALIZATION] and [!REVERSAL] markers, with date+slug context. Read this before audit-trail.md — it is what the loop has actually concluded across runs, and it surfaces learning that predates the most recent Orient run. Generated by record.py learning --write, bounded to a recent window so this read stays cheap regardless of how long the trail gets; if it looks stale relative to audit-trail.md's most recent entries, regenerate it. If .acm/learning-archive.md exists and the recent window doesn't cover what you're looking for, check there before falling back to the full trail.
4. .acm/audit-trail.md — the full history. Read for the evidence behind anything in learning.md that needs its surrounding context, and for any specific prior decision the current run might contradict. With learning.md available, you should rarely need to read audit-trail.md end-to-end.

Bounded destination reads. If a destination contains the exact comments <!-- current-destination: complete --> and <!-- destination-history --> in that order, the content between them is the operator-confirmed complete current mandate. Read that bounded section for routine work. Read the full file when running Destination, when the current section is ambiguous or conflicts with other evidence, or when historical provenance is material to the request. If either comment is absent, malformed, or out of order, read the full file. Never infer a boundary from headings, dates, horizontal rules, or file position.

The destination is where you are going, orientation.md is the current location, the trail is the path. If destination and orientation.md disagree, destination wins (the operator holds the destination); if orientation.md and trail disagree, the trail wins (the trail is the evidence).

If Intent cannot form a defensible current-run mandate because materially different interpretations would produce different outcomes, or because a long autonomous scope would compound an unresolved directional assumption, pause and apply Destination before acting. Explain which unresolved direction makes the conversation necessary. Missing .acm/destination.md alone is never sufficient evidence to trigger Destination.

If the ask is underspecified (for example: "continue", "keep going", "next", or equivalent), do not wait for the operator to inject a topic. Generate one agent-initiated direction question before step 2:

1. Form 1-3 sourced hunches from the destination, orientation.md, and recent trail entries about what structural uncertainty matters most now.
2. State one prioritized falsifiable question that would change what you choose to work on.
3. If no operator answer is available in this run, proceed with your highest-confidence destination-hunch as an explicit assumption and continue.

Treat this as a bootstrap for occasion-independence, not a replacement for operator intent. If a direct operator objective exists, it wins.

This is not ceremony. The most common failure mode in autonomous improvement is solving a precisely-executed wrong problem.

2. Examine

Look at the target. Read what is there. Run what can be run. Form a mental model of how it works and what it is for.

Several lenses are available as thinking tools — not a procedure, not a checklist. Apply the ones the target invites:

• Purpose. Does the target achieve what it is for? Read .acm/destination.md and the target's own README. Is there a gap between the stated goal and what the artifact actually does? Is the design the right one for the job? This lens runs first.
• Inconsistency. Where does the target contradict itself? Mixed conventions, asymmetric handling of similar cases, naming patterns that diverge for no reason. Inconsistency is often a root cause whose symptoms surface elsewhere.
• Overburden. Where is some component asked to do too much? Functions, modules, files, or processes that concentrate too many responsibilities. Overburden concentrates risk: the overburdened component is the one most likely to break and hardest to change.
• Waste. Where does the target carry things that don't earn their existence? Dead code, abstractions with one consumer, validation that can never fire, documentation that restates the obvious. Waste creates cognitive load without contributing value.
• Capability leverage. Has a change in available capability altered what is possible or worthwhile for this target? Determine what matters from the target's purpose and current evidence; availability alone is not evidence of improvement.

If the target's problems don't fit these lenses, describe what you actually see. Add lenses as the target warrants (security posture, performance, type safety, accessibility, whatever applies). Name every lens you apply and what it revealed — including "nothing actionable."

3. Challenge the first read

Ask explicitly:

• What am I not seeing?
• Am I anchored to the most obvious finding and missing a subtler, more important one?
• Is the target's structure itself wrong, such that no incremental fix will help?

The third question is the Kaikaku question. If the answer is yes, do not produce a list of incremental fixes. Argue for redesign. Sketch what a v2 of the target would look like. Estimate the cost of the redesign against the cost of continuing to patch. The decision is the operator's; your job is to make it visible.

If you find nothing the first read missed, say so. Do not manufacture blind spots to appear thorough.

4. Decide, Gate, Offer, and Predict

This step has three parts. Decide on the work for this iteration, honor its execution-authority boundary, then offer candidates for the next iteration.

4a. Decide and Predict

Pick one of:

• One incremental change. The single highest-leverage finding. State why it ranks above the alternatives in one sentence each. Crucially, make a pre-commit prediction: formulate a falsifiable prediction of what this change will achieve and what will not happen, before taking action ("I will change X. I expect Y. I expect Z not to happen."). This is a pre-mortem (Klein, Harvard Business Review, 2007) — stating the failure mode before it can happen, not diagnosing it after.
• Argument for redesign. A statement of why incremental work won't pay off here, and a sketch of what redesign would look like. Stop and surface the argument; do not redesign without confirmation.
• Silence. Nothing actionable was found. State what was examined and why nothing warranted change. Silence claims must be bounded. Name the quality bar this iteration was testing against (e.g. internal text-layer consistency, comparative defensibility under hostile external review, comparator coverage, empirical replication, operational deployability), the surfaces in scope, and the bars not tested by this iteration. Unbounded silence ("nothing actionable found" without naming the bar) is the form most likely to be overturned by the next operator-initiated probe testing a different bar. This advances the convergence chain (Principle 3) and is a legitimate outcome. Origin: this requirement mirrors the named-boundary rule in orient/SKILL.md step 5a; both originate in the manifesto target's retro-v201 → retro-v202 transition (2026-06-04). Full provenance in this repo's .acm/audit-trail.md under entry slug retro-named-boundary-rule-from-manifesto-arc and follow-up slug improve-destination-named-boundary-symmetric.

4b. Honor Execution Authority

Before Act, state the proposed change and its verification in one short sentence:

I want to because , then verify it by .

Determine authority only from explicit evidence in the current prompt or confirmed Destination. Without explicit delegation of this routine gate, ask: Proceed, Stop, or Specify. Wait for the answer.

• Proceed: continue to Act.
• Stop: make no target change; record the stopped decision when it produced a material finding or authority signal.
• Specify: return to Intent with the operator's additional information, then re-examine and decide again. Do not apply the old proposal under a patched mandate.

When this routine gate was explicitly delegated, name the source and scope briefly and continue without waiting. Delegation never answers a Destination question, approves a direction change, bypasses an operator-declared consequential-action gate, or authorizes a deliberate reduction in reasoning, memory, learning, or evidence capability. Host-wide autopilot is not authority evidence because it cannot preserve those distinctions.

4c. Offer Next Moves

After deciding on this iteration's work but before acting, surface a short ranked list of candidate next moves with one-sentence reasoning each. Two or three options is the typical shape; one is fine if only one stands out; zero is fine if convergence was declared.

The candidates should come from this iteration's own examination — blind spots named in step 6a, follow-ups implied by what was changed, structural questions surfaced but deferred. They are not a research project; they are what was already visible while doing this iteration's work.

This is not a step the operator must engage with. The next session may pick from the ranking, redirect entirely, or run another improve loop without picking. Silence from the operator is a valid response. The ranking exists so that:

• A future Orient run can audit: did the operator's selection match the agent's top-ranked option? When it didn't, what redirected it? That comparison is arc-level evidence about how the operator-gate is actually steering the work.
• A fresh-session agent reading the trail has a candidate next move ready, not just an arc-claim, in case the operator's intent is "continue from where you left off."
• The strategic dialogue that has been operating informally as "what should we do next?" exchanges is now visible in the trail as a structural property of every iteration, without becoming a mandatory checklist for the operator.

Write the ranking under a ### Candidate Next Moves subsection inside the trail entry (recorded in step 7). Format: a numbered list, top-ranked first, each item a single sentence stating what the move is and why it ranks where it does. Keep it short — if it grows past a paragraph per item, the candidates are not yet sharp enough to offer.

5. Act (if a change was decided)

Make the change. For each non-trivial step, state what you are about to do and why before doing it. Show the reasoning, not just the diff. After the change, verify it: run tests, check types, re-read the surrounding code to confirm no regression. Evaluate the actual outcome against the prediction made in Step 4. Observe and document if the prediction held or failed.

If the change introduces a problem, surface it immediately. Half-done work that pretends to be done is worse than no work at all.

If you back out of a planned step within this iteration (attempted X, then removed it after Y showed it was wrong), mark it [!REVERSAL] in the trail entry. Within-iteration reversals are as much evidence of honest reasoning as cross-iteration ones; under-marking them produces a trail with implausibly high success density and is a known confabulation pattern.

6. Reflect

Two operations live in this step. The first runs every iteration. The second runs only when the first surfaces a reason for it. Reflection in this skill is always about the target — the codebase, the system, the artefact you are working on — not about the loop that examines it. The loop is only interesting insofar as it reveals or obscures something about the target. For arc-level questions about whether the loop is examining the right parts of the target — questions this step does not answer — use Orient as a standalone skill.

6a. Per-iteration reflection

After the change is made (or silence is declared), but before recording, sit with three things. They are prompts for honest reflection inside the trail entry, not slots to fill.

• State your current model of the target as a claim a future run could disagree with. Not a summary of what you did this run — a falsifiable assertion about what the target is, what it is becoming, or where its real weight sits. Examples of the right shape: "This codebase is converging on X." "The hardest part of this target is Y, and prior runs have consistently misread it as Z." "The real risk in this system lives in W, even though most attention has gone to V." A future iteration examining the same target should be able to read the sentence and say either "still true" or "no, here is what changed my mind."
• Name a blind spot in this run. Something specific you suspect this iteration did not see clearly — an area you did not examine, a kind of evidence you did not gather, an assumption you took on faith. Generic hedging ("I might have missed something") is not a blind spot. If you genuinely cannot name one, say so, and say why ("this run touched only documentation; runtime behaviour was not exercised").
• Imagine a reader who knows this target better than you do. What would they push back on in this run's findings or model? If nothing comes to mind, the run probably did not engage the target deeply enough.

When something material surfaces — an updated model, a contradiction with a prior run, a blind spot worth carrying forward — write it as [!REALIZATION] in the entry. That is the storage mechanism. No new markers are introduced for reflection.

6b. Across-trail reflection

Most iterations do not perform the macro reflection. But every iteration must evaluate whether to perform it, and record that evaluation in the trail entry. The check is cheap; the cost discipline lives in what the check decides, not in skipping the check.

Evaluate each of the four triggers explicitly, with brief evidence drawn from the trail. Bare "N/A" is not allowed. The format for the entry is one short line per trigger, e.g.:

• Recurring finding-class: FIRED — last 4 entries were paragraph-add, encoding-fix, label-add, section-removal (all mechanical inconsistency cleanups).
• About to declare silence: not fired — this run made a change.
• Contradicts prior [!REALIZATION]: not fired — checked last 10 realisations, none contradicted.
• Operator explicitly asked: not fired.

If any trigger fired, perform the macro reflection. If none fired, the entry still records the evaluation — that is the audit trail showing the check was made, not skipped.

Why this is structural, not ceremonial: the recurring-class trigger has historically been the one most often quietly waived. Recording the evaluation makes "I didn't notice the pattern" distinguishable from "I noticed and judged it didn't fire," and makes both visible to the next iteration.

When the macro reflection runs, read .acm/audit-trail.md as a single document about the target, not as a list of past runs. Then sit with this:

• Which prior realisations aged well, and which were wrong in retrospect? If the trail is long enough, name at least one of each.
• Where has attention been spent, and is that where the target's real weight lies? A long tail of small fixes in one corner can mean either "that corner is the bottleneck" or "this is the corner the loop has grown comfortable looking at." The trail itself is the evidence — re-read it.
• What does the target need next that no individual iteration would have surfaced — only the arc reveals?
• Is the recurring pattern a single-loop symptom or a double-loop signal? Single-loop correction fixes the action while leaving the governing variable that produced it untouched — the goal, constraint, or assumption in .acm/destination.md (or an unstated assumption the loop has been carrying) that shaped every one of the recurring fixes. If the same finding-class keeps recurring despite repeated correction, the recurrence itself is evidence that the governing variable, not the action, is the actual defect. Name the specific governing variable implicated, state it as a candidate destination-revision (not another artifact patch), and route it to the operator via the Destination skill rather than proposing a fifth fix for the same symptom. (Argyris, Organizational Learning, 1977 — single-loop learning corrects action within existing governing variables; double-loop learning questions and revises the governing variables themselves.)

Write the result as [!REALIZATION] in this entry, framed as a claim about the target. If it changes the priority for the next iteration, say so plainly.

For an arc-read that runs outside an improve iteration, use Orient.

7. Record

Before applying Trail, answer two questions from current evidence:

1. Does the next work depend on durable direction the operator has not settled? If yes, schedule Destination. Name the unresolved choice; missing files, age, and iteration count are never reasons by themselves.
2. Does the current Orientation still explain the governing Destination and the material trail? If no, or if a multi-run convergence claim now depends on that arc-read, schedule Orient. Name the evidence the current map misses; cadence is never a reason by itself.

These are purpose tests, not trigger checklists. Do not make the operator orchestrate the services.

Include one line in the Trail entry: Orientation freshness: current or Orientation freshness: STALE — <evidence>; automatic Orient scheduled. This evaluation must be inside the entry before it becomes append-only history.

Include one line beside it: Destination need: not triggered or Destination need: TRIGGERED — <evidence>; automatic Destination scheduled.

Apply Trail automatically now. Trail is an egress service of the full suite, not a command the operator must remember to invoke. Do not ask the operator to run it separately.

High-Fidelity Mode (Writer Splitting): Standard mode is the default: the Improve agent applies Trail automatically. High-Fidelity Mode is active only when the operator explicitly requests independent Trail authorship or an execution contract declared it before the run; task consequence alone does not activate it. Before step 5 (Act), confirm that the current host can invoke a separate agent and return control to this run. If that round trip cannot be established, treat the writer as unavailable: stop before acting and ask whether standard mode is acceptable.

When active, the Improve agent pauses at this step without writing the entry and hands the independent writer its interpretation, examination, decision, pre-action prediction, action evidence, reflection, and exact Destination/Orientation evaluations. The writer applies Trail and commits the entry without recomputing Improve's decisions, then returns control. The Improve agent resumes at step 8. This separates writer from decider without changing who owns service scheduling.

In multi-iteration runs, this step executes after every iteration — not once at the end of all iterations. The trail entry is the commit point for that iteration. Append it, regenerate history.md, and commit before starting the next iteration. A user who stops a 10-iteration run after iteration 4 must have 4 committed trail entries, not 0.

If this is a standalone Improve installation and Trail is unavailable: create the .acm/ directory in the target repo root if it does not already exist, then append a single entry to .acm/audit-trail.md in the target repo root (not the skills install directory). The entry must include:

• Date, target, operator (if known), model identity (provider + tool-call ID prefix if observable).
• Your interpretation of the ask.
• Lenses applied and what each revealed.
• The decision (incremental, redesign argument, or silence) and the pre-commit prediction.
• The change made and verification evidence — including a comparison of the actual outcome versus the prediction — or, if silence, a statement of what was examined.
• Reflection about the target (per step 6): a falsifiable model-claim, a named blind spot, and an imagined-reader pushback. Across-trail reflection if its triggers fired.
• Marked moments: [!DECISION], [!REVERSAL], [!REALIZATION].

The format spec is in trail/SKILL.md. If you have the skills repository clone, its optional <skills-repo>/harness/tools/record.py helper can stub a new entry for you; the one-line skill installer does not copy this helper.

8. Run scheduled services

After the Trail entry is durable, apply Destination first if step 7 scheduled it. Destination synthesizes the accepted prompt-level mandates and accumulated evidence instead of asking the operator to describe the project from zero. It asks only the highest-priority unresolved sourced question, waits for confirmation or correction, and records the result. A confirmed Destination governs the next Improve iteration; it does not retroactively authorize or rewrite the completed one.

Then apply Orient if needed. When Improve already scheduled Orient and Destination materially changes direction, the post-Destination Orient satisfies both needs: run it once, against the changed Destination and full trail. Orient writes its own Trail entry and refreshes .acm/orientation.md; it never changes the target. If neither service was scheduled, stop without ceremony.

9. Report the result

End with exactly one crisp operator-facing result line. Use the matching shape:

• Changed: Changed <target>: <what changed and why>. Verification: <result>.
• Silence: No change to <target>: tested <quality bar> across <scope>; nothing actionable found. Verification: <result>.
• Redesign: No change to <target>: redesign recommended because <reason>. Evidence: <result>.
• Stopped: Stopped before changing <target>: <proposal> was not authorized. Verification: no target change.
• Failed: Could not complete <target>: <blocker or failure>. Verification: <what did and did not run>.

Link to detailed evidence instead of repeating the Trail.

Self-targeting

This skill must be runnable on itself. If running Improve on improve/SKILL.md and probe/SKILL.md produces nothing actionable, that is evidence the skills are simple enough. If it produces a list of fixes, do them. If it produces an argument for redesign, surface it.

What this skill does not do

• It does not score the target on a numerical rubric. v2 did this and the question "who made up these metrics?" never went away. Convergence — diverse independent evaluators finding nothing to change — is the only honest measure of done.
• It does not make the operator orchestrate support skills. In the full suite, Improve automatically applies Intent at ingress, Trail at egress, Destination when durable direction becomes necessary, and Orient when accumulated evidence makes Orientation stale. A standalone Improve installation retains local fallback behavior when a sibling is unavailable.
• It does not treat host-wide autopilot as blanket permission. Routine gates may be explicitly delegated; operator-owned direction and consequential gates remain blocking.
• It does not tell you when to stop. The convergence protocol in PRINCIPLES.md does.