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
2 changes: 1 addition & 1 deletion GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
3 changes: 2 additions & 1 deletion skills/simplify-code/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -13,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/<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.
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/<date>-<scope>-<unique-id>/`, 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.
Expand Down
3 changes: 3 additions & 0 deletions skills/simplify-code/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
interface:
display_name: 'Simplify Code'
short_description: 'Relentlessly reduce code while preserving behaviour'

policy:
allow_implicit_invocation: false
11 changes: 6 additions & 5 deletions skills/simplify-code/assets/progress.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
8 changes: 4 additions & 4 deletions skills/simplify-code/references/recovery.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# 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.

## Checkpoint and resume

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.
Loading