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
4 changes: 4 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,7 @@
### Software quality

**Deterministic measurement**: A reproducible tool-produced observation of one named property of a fixed software candidate, with its scope, components, configuration, limitations, and comparison basis preserved. An attention threshold requires appraisal but is not by itself a defect, an overall quality score, or permission to weaken behaviour or design.

**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.
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ Choose the skill for the outcome you need. Each invocation finishes its own task
| [$commit](skills/commit/SKILL.md) | Record all uncommitted branch changes in atomic Conventional Commits. |
| [$pull-request](skills/pull-request/SKILL.md) | Publish the branch for review. Commit any remaining changes, push the branch, and create or update its pull request. |
| [$review-pull-request](skills/review-pull-request/SKILL.md) | Independently assess an existing PR against engineering standards and available requirements. Return findings for you to act on. |
| [$simplify-code](skills/simplify-code/SKILL.md) | Aggressively simplify a feature, module or codebase while preserving behaviour. Produce verified changes and a durable running report. |
| [$debug](skills/debug/SKILL.md) | Investigate a failure and establish its cause. Ask for diagnosis alone or a repair with implementation and verification. |
| [$upgrade-dependencies](skills/upgrade-dependencies/SKILL.md) | Update dependencies and build or CI tooling through checked migrations. Include language or runtime upgrades when requested. |

Expand Down Expand Up @@ -91,6 +92,10 @@ $review-pull-request #12 against @docs/features/reading-list/specification.md

As Shelf grows, use the maintenance entry points for specific needs:

```text
$simplify-code Shelf's reading list feature
```

```text
$debug and fix Shelf adding the same book twice when I submit the form once
```
Expand Down
4 changes: 2 additions & 2 deletions skills/pull-request/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,12 @@ Take the branch to publish from the request or current Git state. Resolve the ho
## Method

1. Read [$commit](../commit/SKILL.md) for the title conventions. Invoke it whenever uncommitted changes exist. Continue only after it completes.
2. Inspect the complete branch diff against its base, including earlier commits. Invoke [$write-prose](../write-prose/SKILL.md) for a Conventional Commit title summarising the full change and a succinct description covering **what changed, why, and the resulting behaviour**. Keep required PR template fields and material evidence or limitations. Reuse valid checks and distinguish local evidence from remote CI status.
2. Inspect the complete branch diff against its base, including earlier commits. Invoke [$write-prose](../write-prose/SKILL.md) for a Conventional Commit title summarising the full change and a succinct description covering **what changed, why, and the resulting behaviour**. Include limitations only when they affect interpretation of the implemented behaviour. Preserve required PR template fields. Keep routine check results and execution history out of the description unless a required template field calls for them.
3. Push the intended branch without rewriting remote history. Reuse a matching open PR and check its title and description against the full diff and these requirements. Update either when stale or noncompliant. Otherwise create one PR, ready by default. Preserve an existing PR's readiness unless directed to change it. After an uncertain mutation result, read host state before retrying to avoid duplicates.
4. Read back the PR's URL, title, body, head, base, readiness, and published revision. Verify that the revision matches the intended local head and that the metadata describes the complete change.

## Finish

Return the PR title and URL with any blocker or material validation limitation.
Return the PR title and URL. Report available check results, blockers and material validation limitations in the chat handoff, distinguishing local evidence from remote CI status.

**Done only when** all uncommitted work is recorded and the matching open PR contains the intended revision, base, readiness, title, and description. Report failures with remaining work preserved. Stop before review, merge, release, deployment, or ongoing CI monitoring.
27 changes: 27 additions & 0 deletions skills/simplify-code/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
name: simplify-code
description: Aggressively reduce code and maintenance burden when a feature, module, file or codebase needs sustained behaviour-preserving simplification.
---

# Simplify code

Aggressively reduce code and maintenance burden. Relentlessly challenge unnecessary mechanisms and tests. **Subtract before adding. Preserve observable behaviour.**

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

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

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

**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.
3 changes: 3 additions & 0 deletions skills/simplify-code/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
interface:
display_name: 'Simplify Code'
short_description: 'Relentlessly reduce code while preserving behaviour'
44 changes: 44 additions & 0 deletions skills/simplify-code/assets/progress.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Simplification run

## Current checkpoint

- Status: {Active, Blocked, Interrupted or Complete}
- Objective and scope: {requested outcome and complete logical scope}
- Constraints and exclusions: {behaviour to preserve and boundaries}
- Current candidate: {compact ID and inventory link}
- Clean-review count: {0–3, candidate and ordered qualifying 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}
- Behaviour: {supported entries, consumers, guarantees and verification}
- Measurements: {baseline report, production size, test size and limitations}
- Initial checks: {results and pre-existing failures}

## Decisions and finding dispositions

| Report and finding | Candidate | Disposition | Evidence and reason | Result or next action |
| ------------------ | --------- | -------------------------------------- | ------------------- | -------------------------------------------- |
| {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.

## 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.}

## Verification and evidence

| Evidence | Candidate and scope | Result and applicability |
| ----------------------------------------------- | ------------------- | ------------------------------------------------------ |
| {report link or check command and saved output} | {ID and coverage} | {outcome, current or historical, material limitations} |

## Outstanding work and blockers

{Unresolved findings, missing coverage, exact blockers, attempted paths and needed input. 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.}
23 changes: 23 additions & 0 deletions skills/simplify-code/references/recovery.md
Original file line number Diff line number Diff line change
@@ -0,0 +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.

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

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.

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

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 counter only when its qualifying evidence remains current. Reconstruct missing state from available evidence, making gaps explicit. Never infer an undocumented clean sequence.
Loading