Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions skills/simplify-code/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<date>-<scope>-<unique-id>/`, 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.
8 changes: 5 additions & 3 deletions skills/simplify-code/assets/progress.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand All @@ -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

Expand All @@ -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.}
4 changes: 2 additions & 2 deletions skills/simplify-code/references/recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Loading