From b6b90d5dedb39fd7c1afb5c09fe3a5593ea39234 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Thu, 8 Oct 2026 20:11:26 +0100 Subject: [PATCH 1/3] fix(simplify-code): cap outer cleanup iterations --- skills/simplify-code/SKILL.md | 14 +++++++++----- skills/simplify-code/assets/progress.md | 8 +++++--- skills/simplify-code/references/recovery.md | 4 ++-- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/skills/simplify-code/SKILL.md b/skills/simplify-code/SKILL.md index 366e06b..26fd52a 100644 --- a/skills/simplify-code/SKILL.md +++ b/skills/simplify-code/SKILL.md @@ -9,19 +9,23 @@ Aggressively reduce code and maintenance burden. Relentlessly challenge unnecess ## Inputs -Take the feature, module, file or codebase from the request. Include related unchanged code and tests across the affected capability. Preserve unrelated work. Resolve material scope or preservation uncertainty through [$elicit-with-context](../elicit-with-context/SKILL.md) before dependent changes. +Take the feature, module, file or codebase from the request. Default to **10 outer iterations**, overridable by the caller. Include related unchanged code and tests across the affected capability. Preserve unrelated work. Resolve material scope or preservation uncertainty through [$elicit-with-context](../elicit-with-context/SKILL.md) before dependent changes. ## Method 1. **Establish the run.** Read repository instructions. Inventory the complete scope, supported entries, consumers and observable guarantees. Record the starting revision and relevant working-tree state. Create a unique run directory at `docs/simplification/--/`, unless the caller supplies a destination, and report its absolute path. Use [the running report template](assets/progress.md). Read [recovery and evidence](references/recovery.md) when establishing or resuming a run, and maintain that record throughout. 2. **Measure the baseline.** Invoke [$measure-code-complexity](../measure-code-complexity/SKILL.md) with explicit production paths covering the complete logical scope. Its changed-file default is insufficient. Record existing check results and pre-existing failures. Track production and test size separately. Apply [$test-design](../test-design/SKILL.md) to the related suite, identifying meaningful promises and unnecessary test burden. -3. **Relentlessly examine.** Invoke [$code-cleanup](../code-cleanup/SKILL.md) on the fixed candidate and complete scope, including tests and supporting implementation. Supply the preservation baseline, repository instructions and current measurements. Keep the running report, adjudication history and prior conclusions outside fresh reviewer packets. Pursue whole mechanisms, duplicated rules, unnecessary state, redundant transformations and abstractions that do not earn their cost. Use **YAGNI** and **DRY**. Lower scores and fewer lines alone cannot justify dense code or displaced complexity. +3. **Relentlessly examine.** Check the stopping rules below before starting another iteration. Increment and checkpoint the total iteration count before invoking [$code-cleanup](../code-cleanup/SKILL.md) on the fixed candidate and complete scope, including tests and supporting implementation. Supply the preservation baseline, repository instructions and current measurements. Keep the running report, adjudication history and prior conclusions outside fresh reviewer packets. Pursue whole mechanisms, duplicated rules, unnecessary state, redundant transformations and abstractions that do not earn their cost. Use **YAGNI** and **DRY**. Lower scores and fewer lines alone cannot justify dense code or displaced complexity. 4. **Adjudicate and implement.** Read every report and give every finding an evidence-backed disposition. Resolve preservation gaps before transforming code. Deliver every justified simplification through [$implement](../implement/SKILL.md), including necessary test repairs and deletion of newly orphaned artefacts. Reject incorrect or disproportionate recommendations with concrete evidence. Aggressively reduce the overall maintenance burden while retaining meaningful behavioural protection. Do not weaken assertions, checks or quality thresholds to enable deletion. 5. **Verify the candidate.** After changes, refresh affected checks and the complete relevant existing suite. Remeasure the same logical production scope, accounting for additions, renames and deletions. Obtain current [$code-review](../code-review/SKILL.md) coverage of the complete scope and resolve its findings. Reuse implementation evidence only where its candidate and coverage match. Account for formatter and generator edits before trusting final evidence. -6. **Repeat to saturation.** Maintain a consecutive clean-review counter, initially zero. Count only outer-loop cleanup reviews that are fresh, current, complete for the agreed scope and leave no justified implementable findings after evidenced adjudication. Empty reports and concretely disproved findings can qualify. An incomplete or stale review, unresolved finding or unexplained rejection breaks the sequence and resets it to zero. Any substantive change to reviewed code, tests, supporting implementation, scope or preservation baseline also resets it. Log and evidence updates do not. Commission another fresh cleanup review until the count reaches three on the unchanged candidate. Inner implementation cleanup does not count. Three improvement cycles do not satisfy this gate. Continue for as many cycles as necessary, without a deletion quota or arbitrary iteration limit. +6. **Stop at saturation or the limit.** Maintain two counters, both initially zero. An outer iteration includes one cleanup review, adjudication and any resulting implementation and verification. The total counts every commissioned outer review, including clean confirmation passes and incomplete or stale attempts. It never resets after changes, compaction or resumption. Inner implementation reviews do not count toward either counter. + + The consecutive clean-review counter counts only fresh, current, complete outer reviews that leave no justified implementable findings after evidenced adjudication. Empty reports and concretely disproved findings can qualify. An incomplete or stale review, unresolved finding or unexplained rejection resets this counter to zero. Any substantive change to reviewed code, tests, supporting implementation, scope or preservation baseline also resets it. Log and evidence updates do not. + + Finish as **Saturated** when three consecutive qualifying reviews cover the unchanged candidate. Otherwise finish as **Iteration limit reached** when the total reaches the limit. Finish an iteration already underway, including accepted changes, necessary corrections, checks and independent review, before handing back. Start no further outer review to obtain clean confirmations or pursue low-priority findings beyond the limit. A budget-limited finish is normal and leaves saturation unproven. Record remaining recommendations and gaps rather than silently dropping them. Apply no deletion quota. ## Finish -Return a link to `progress.md` and a concise summary of significant deletions and simplifications, preserved behaviour, separate production and test reductions, before-and-after measurements, checks, independent review, the three qualifying cleanup reports and material limitations. +Return a link to `progress.md` and a concise summary of significant deletions and simplifications, preserved behaviour, separate production and test reductions, before-and-after measurements, checks, independent review, stopping reason, iterations used against the limit, qualifying cleanup reports, remaining recommendations and material limitations. -**Done only when** the complete scope is accounted for, all justified changes and accepted findings are implemented, observable behaviour is preserved, required checks and independent review are current, three consecutive qualifying cleanup reviews cover the unchanged final candidate, and the running report has no unresolved completion blockers. Three reviews are the stopping rule, not proof of optimal simplicity. If blocked or interrupted, record the exact blocker, attempted paths and next useful action, and report incomplete work. Leave a local reviewable result. Commit, publication and deployment require separate instructions. +**Done only when** the complete scope is accounted for, accepted changes are implemented and verified, observable behaviour is preserved, required checks and independent review are current, either stopping condition holds, and the running report records the outcome and remaining work. Unresolved correctness, preservation or verification blockers leave the run incomplete even at the limit. The saturated outcome is a stopping rule, not proof of optimal simplicity. If blocked or interrupted, record the exact blocker, attempted paths and next useful action, and report incomplete work. Leave a local reviewable result. Commit, publication and deployment require separate instructions. diff --git a/skills/simplify-code/assets/progress.md b/skills/simplify-code/assets/progress.md index 0d8022c..2da60ab 100644 --- a/skills/simplify-code/assets/progress.md +++ b/skills/simplify-code/assets/progress.md @@ -3,9 +3,11 @@ ## Current checkpoint - Status: {Active, Blocked, Interrupted or Complete} +- Stopping reason: {Saturated, Iteration limit reached, or not yet stopped} - Objective and scope: {requested outcome and complete logical scope} - Constraints and exclusions: {behaviour to preserve and boundaries} - Current candidate: {compact ID and inventory link} +- Outer iterations: {total commissioned / limit, including pending or failed attempts} - Clean-review count: {0–3, candidate and ordered qualifying report links} - Next useful action: {concrete continuation} @@ -27,7 +29,7 @@ Record user questions, answers and resulting changes of direction here. Link a c ## Significant outcomes -{Mechanisms removed or simplified, meaningful test changes and preservation evidence. Retain significant checkpoints and counter resets. Leave line-level edits to the Git diff.} +{Mechanisms removed or simplified, meaningful test changes and preservation evidence. Retain significant checkpoints, numbered outer review attempts and clean-counter resets. Leave line-level edits to the Git diff.} ## Verification and evidence @@ -37,8 +39,8 @@ Record user questions, answers and resulting changes of direction here. Link a c ## Outstanding work and blockers -{Unresolved findings, missing coverage, exact blockers, attempted paths and needed input. Use None only when resolved.} +{Remaining recommendations and their priorities, missing coverage, exact blockers, attempted paths and needed input. Distinguish deferred simplification from correctness or verification blockers. Use None only when resolved.} ## Final outcome -{Complete only at the skill's finish gate. Summarise production and test reductions separately, comparable measurements, preserved behaviour, current verification, the three qualifying report links and material limitations.} +{Complete only at the skill's finish gate. State the stopping reason and iterations used / limit. Summarise production and test reductions separately, comparable measurements, preserved behaviour, current verification, qualifying review links, remaining recommendations and material limitations. A limit-reached outcome leaves saturation unproven.} diff --git a/skills/simplify-code/references/recovery.md b/skills/simplify-code/references/recovery.md index 8b732a8..f2bb7bc 100644 --- a/skills/simplify-code/references/recovery.md +++ b/skills/simplify-code/references/recovery.md @@ -8,7 +8,7 @@ Keep a path and content-fingerprint inventory for the complete reviewed scope an Give the inventory a compact candidate ID and retain older inventories. Record the scope and preservation baseline alongside it. Exclude the run's own logs and evidence. Recheck identity before and after reviews and checks, and after tools that can edit files. Detect newly introduced paths as well as changes to existing paths. Candidate drift invalidates affected evidence and the clean-review sequence under the root skill's counter rules. -For example, two clean reviews followed by a test deletion require three new qualifying reviews. Changing only a report's finding disposition does not alter the candidate, but an unresolved preservation gap still prevents that review from qualifying. +For example, at iteration 9 of 10, a test deletion resets two clean reviews to zero but leaves only one outer iteration available. Finish that iteration and verification, then report the limit rather than commissioning three more reviews. Changing only a report's finding disposition does not alter the candidate, but an unresolved preservation gap still prevents that review from qualifying. ## Preserve usable evidence @@ -20,4 +20,4 @@ Index checks by candidate, command, actual result and material environment limit Update the record after meaningful changes, adjudications, verification, user questions and answers, blockers and counter transitions, and before ending a turn. Keep significant decisions, rejected findings and their reasons, unresolved work and the next useful action. Retain enough history to explain the final outcome without a command transcript. -After compaction or resumption, read the running report and relevant linked evidence before continuing. Reconcile the inventory, candidate, scope and preservation baseline with the actual working tree. Trust the counter only when its qualifying evidence remains current. Reconstruct missing state from available evidence, making gaps explicit. Never infer an undocumented clean sequence. +After compaction or resumption, read the running report and relevant linked evidence before continuing. Reconcile the inventory, candidate, scope and preservation baseline with the actual working tree. Trust the clean-review counter only when its qualifying evidence remains current. Preserve the total iteration count and configured limit across resumption, including an iteration already commissioned before interruption. Reconstruct missing counts from recorded outer review attempts, never from clean reviews alone. Make reconstruction gaps explicit rather than granting a fresh budget. If the limit is already reached, finish outstanding verification and hand back without another outer review. Never infer an undocumented clean sequence. From f7371a27b5a290882fdfc51cd028d11fabfa5fd5 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Fri, 9 Oct 2026 21:37:47 +0100 Subject: [PATCH 2/3] fix(simplify-code): require explicit invocation --- skills/simplify-code/SKILL.md | 1 + skills/simplify-code/agents/openai.yaml | 3 +++ 2 files changed, 4 insertions(+) diff --git a/skills/simplify-code/SKILL.md b/skills/simplify-code/SKILL.md index 26fd52a..ab555e1 100644 --- a/skills/simplify-code/SKILL.md +++ b/skills/simplify-code/SKILL.md @@ -1,6 +1,7 @@ --- name: simplify-code description: Aggressively reduce code and maintenance burden when a feature, module, file or codebase needs sustained behaviour-preserving simplification. +disable-model-invocation: true --- # Simplify code diff --git a/skills/simplify-code/agents/openai.yaml b/skills/simplify-code/agents/openai.yaml index d2ad817..2a4e783 100644 --- a/skills/simplify-code/agents/openai.yaml +++ b/skills/simplify-code/agents/openai.yaml @@ -1,3 +1,6 @@ interface: display_name: 'Simplify Code' short_description: 'Relentlessly reduce code while preserving behaviour' + +policy: + allow_implicit_invocation: false From ab1ae7d81888d4b19b0d263aebb9ca68cd1ada3d Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Fri, 9 Oct 2026 21:37:58 +0100 Subject: [PATCH 3/3] fix(simplify-code): store disposable artefacts in OS temp --- GLOSSARY.md | 2 +- skills/simplify-code/SKILL.md | 2 +- skills/simplify-code/assets/progress.md | 11 ++++++----- skills/simplify-code/references/recovery.md | 8 ++++---- 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index ee85999..3dbdcb2 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -24,4 +24,4 @@ **Simplification run**: A sustained simplification of a requested feature, module or codebase, including its related tests, driven by complexity measurement and independent cleanup reviews. Accepted changes are delivered through the implementation skill while preserving observable behaviour. -**Running report**: The durable recovery record for a simplification run, retaining scope, constraints, decisions, evidence, outstanding work and completion progress across context compaction. It supports the final summary without reproducing the Git diff. +**Running report**: The sole durable recovery record for a simplification run, retaining scope, constraints, decisions, essential evidence, outstanding work and completion progress across context compaction and resumption. Supporting artefacts are disposable, so recovery relies on the report's contents. It supports the final summary without reproducing the Git diff. diff --git a/skills/simplify-code/SKILL.md b/skills/simplify-code/SKILL.md index ab555e1..8ef56f7 100644 --- a/skills/simplify-code/SKILL.md +++ b/skills/simplify-code/SKILL.md @@ -14,7 +14,7 @@ Take the feature, module, file or codebase from the request. Default to **10 out ## Method -1. **Establish the run.** Read repository instructions. Inventory the complete scope, supported entries, consumers and observable guarantees. Record the starting revision and relevant working-tree state. Create a unique run directory at `docs/simplification/--/`, unless the caller supplies a destination, and report its absolute path. Use [the running report template](assets/progress.md). Read [recovery and evidence](references/recovery.md) when establishing or resuming a run, and maintain that record throughout. +1. **Establish the run.** Read repository instructions. Inventory the complete scope, supported entries, consumers and observable guarantees. Record the starting revision and relevant working-tree state. Create `progress.md` at `docs/simplification/--/`, unless the caller supplies a destination. Store all supporting artefacts in a unique run directory in the OS temporary directory by default. Report both absolute paths. Use [the running report template](assets/progress.md). Read [recovery and evidence](references/recovery.md) when establishing or resuming a run, and maintain that record throughout. 2. **Measure the baseline.** Invoke [$measure-code-complexity](../measure-code-complexity/SKILL.md) with explicit production paths covering the complete logical scope. Its changed-file default is insufficient. Record existing check results and pre-existing failures. Track production and test size separately. Apply [$test-design](../test-design/SKILL.md) to the related suite, identifying meaningful promises and unnecessary test burden. 3. **Relentlessly examine.** Check the stopping rules below before starting another iteration. Increment and checkpoint the total iteration count before invoking [$code-cleanup](../code-cleanup/SKILL.md) on the fixed candidate and complete scope, including tests and supporting implementation. Supply the preservation baseline, repository instructions and current measurements. Keep the running report, adjudication history and prior conclusions outside fresh reviewer packets. Pursue whole mechanisms, duplicated rules, unnecessary state, redundant transformations and abstractions that do not earn their cost. Use **YAGNI** and **DRY**. Lower scores and fewer lines alone cannot justify dense code or displaced complexity. 4. **Adjudicate and implement.** Read every report and give every finding an evidence-backed disposition. Resolve preservation gaps before transforming code. Deliver every justified simplification through [$implement](../implement/SKILL.md), including necessary test repairs and deletion of newly orphaned artefacts. Reject incorrect or disproportionate recommendations with concrete evidence. Aggressively reduce the overall maintenance burden while retaining meaningful behavioural protection. Do not weaken assertions, checks or quality thresholds to enable deletion. diff --git a/skills/simplify-code/assets/progress.md b/skills/simplify-code/assets/progress.md index 2da60ab..9440923 100644 --- a/skills/simplify-code/assets/progress.md +++ b/skills/simplify-code/assets/progress.md @@ -6,17 +6,18 @@ - Stopping reason: {Saturated, Iteration limit reached, or not yet stopped} - Objective and scope: {requested outcome and complete logical scope} - Constraints and exclusions: {behaviour to preserve and boundaries} -- Current candidate: {compact ID and inventory link} +- Current candidate: {compact ID, inventory reconstruction basis and optional inventory link} +- Supporting artefacts: {absolute temporary run directory, disposable} - Outer iterations: {total commissioned / limit, including pending or failed attempts} -- Clean-review count: {0–3, candidate and ordered qualifying report links} +- Clean-review count: {0–3, candidate, ordered qualifying review identities, coverage and conclusions, with optional report links} - Next useful action: {concrete continuation} ## Baseline and coverage - Baseline: {revision, starting dirty state and preserved unrelated work} -- Inventory: {production, tests, supporting paths and coverage status, or link} +- Inventory: {production, tests, supporting paths and coverage status, with optional detail link} - Behaviour: {supported entries, consumers, guarantees and verification} -- Measurements: {baseline report, production size, test size and limitations} +- Measurements: {baseline results, production size, test size and limitations, with optional report link} - Initial checks: {results and pre-existing failures} ## Decisions and finding dispositions @@ -25,7 +26,7 @@ | ------------------ | --------- | -------------------------------------- | ------------------- | -------------------------------------------- | | {link and ID} | {ID} | {Accepted, Rejected or Needs evidence} | {concrete basis} | {implemented checkpoint or resolving action} | -Record user questions, answers and resulting changes of direction here. Link a companion ledger if this section becomes too large. +Record user questions, answers and resulting changes of direction here. Keep essential findings, dispositions and reasons in this report. Link a disposable companion ledger for additional detail if this section becomes too large. ## Significant outcomes diff --git a/skills/simplify-code/references/recovery.md b/skills/simplify-code/references/recovery.md index f2bb7bc..e414908 100644 --- a/skills/simplify-code/references/recovery.md +++ b/skills/simplify-code/references/recovery.md @@ -1,18 +1,18 @@ # Recovery and evidence -Keep `progress.md` compact enough to read before resuming work. Refresh current state and applicable verification in place, and label older evidence as historical. Use [the template](../assets/progress.md) for current state and durable decisions. Link larger inventories and evidence rather than copying their contents. Add companion files only when they keep the main record useful. The Git diff owns line-level change detail. +Keep `progress.md` compact enough to read before resuming work. It is the sole durable recovery record. Refresh current state and applicable verification in place, and label older evidence as historical. Use [the template](../assets/progress.md) for current state and durable decisions. Summarise all information needed to resume in the report itself. Link larger inventories and evidence as disposable supporting artefacts in the temporary run directory. The Git diff owns line-level change detail. ## Fix the candidate Keep a path and content-fingerprint inventory for the complete reviewed scope and inspected implementation dependencies, including production, tests, configuration and eligible untracked files. Record deletions, file modes and relevant external source identities where applicable. Record the baseline revision and staged, unstaged and untracked starting work separately. `HEAD` alone cannot identify a dirty candidate. The measurement tool's production-only content ID cannot identify the reviewed tests or supporting implementation. -Give the inventory a compact candidate ID and retain older inventories. Record the scope and preservation baseline alongside it. Exclude the run's own logs and evidence. Recheck identity before and after reviews and checks, and after tools that can edit files. Detect newly introduced paths as well as changes to existing paths. Candidate drift invalidates affected evidence and the clean-review sequence under the root skill's counter rules. +Give the inventory a compact candidate ID and retain older inventories. Record the candidate ID, inventory reconstruction basis, scope and preservation baseline in `progress.md`. Exclude the run's own logs and evidence. Recheck identity before and after reviews and checks, and after tools that can edit files. Detect newly introduced paths as well as changes to existing paths. Candidate drift invalidates affected evidence and the clean-review sequence under the root skill's counter rules. For example, at iteration 9 of 10, a test deletion resets two clean reviews to zero but leaves only one outer iteration available. Finish that iteration and verification, then report the limit rather than commissioning three more reviews. Changing only a report's finding disposition does not alter the candidate, but an unresolved preservation gap still prevents that review from qualifying. ## Preserve usable evidence -Archive measurement, cleanup and code-review reports into the run directory as they arrive, including reports produced inside `$implement`. Preserve original findings, provenance and candidate identity. Keep caller dispositions separately in the running report. Copy linked evidence needed to understand an archived report, and verify that its references remain usable. Temporary paths alone are insufficient recovery storage. +Collect measurement, cleanup and code-review reports in the temporary run directory as they arrive, including reports produced inside `$implement`. Preserve original findings, provenance and candidate identity there. Record essential findings, dispositions, measurements, review coverage and conclusions in `progress.md`, including the candidate and provenance for each. Temporary links supplement this recovery information. Index checks by candidate, command, actual result and material environment limitations. Preserve earlier results as historical evidence and identify which results remain current. Record pre-existing failures separately. A matching source identity does not establish live integration compatibility or make an old external observation current. @@ -20,4 +20,4 @@ Index checks by candidate, command, actual result and material environment limit Update the record after meaningful changes, adjudications, verification, user questions and answers, blockers and counter transitions, and before ending a turn. Keep significant decisions, rejected findings and their reasons, unresolved work and the next useful action. Retain enough history to explain the final outcome without a command transcript. -After compaction or resumption, read the running report and relevant linked evidence before continuing. Reconcile the inventory, candidate, scope and preservation baseline with the actual working tree. Trust the clean-review counter only when its qualifying evidence remains current. Preserve the total iteration count and configured limit across resumption, including an iteration already commissioned before interruption. Reconstruct missing counts from recorded outer review attempts, never from clean reviews alone. Make reconstruction gaps explicit rather than granting a fresh budget. If the limit is already reached, finish outstanding verification and hand back without another outer review. Never infer an undocumented clean sequence. +After compaction or resumption, read the running report and any available relevant linked evidence before continuing. Reconstruct a missing inventory using the report and reconcile the candidate, scope and preservation baseline with the actual working tree. Trust the clean-review counter only when its qualifying evidence recorded in the report remains current. Missing disposable files alone do not restart the run or reset its counters. Preserve the total iteration count and configured limit across resumption, including an iteration already commissioned before interruption. Reconstruct missing counts from recorded outer review attempts, never from clean reviews alone. Make reconstruction gaps explicit rather than granting a fresh budget. If the limit is already reached, finish outstanding verification and hand back without another outer review. Never infer an undocumented clean sequence.