simplify

---

name: simplify description: "Simplify code, plans and systems without losing required outcomes; delete machinery that earns nothing; for code, AST-measured complexity with regression gates. Triggers: simplify, refactor, complexity, overengineered, dead code, useless guard." user-invocable: true allowed-tools: Agent, Bash, Read, Edit, Grep, Glob kernel: kind: workflow version: 1 side_effects: writes_source confirmation: none

For code, this skill forces a measured per-function number, records its movement, and installs the same check in the project's normal verification. Prose about "cleaner code" is not accepted.

Adapted from saurabhkumar8112/cyclomatic-complexity-skill (Apache-2.0). The refactoring model never signs its own result; a verifier re-measures and runs the armed project gate.

<on_start> agentdb recall "simplify complexity <files/symbols>" --global </on_start>

<deletion_doctrine> Deletion beats repair. When something is broken, the first question is whether it should exist.

• Broken test: is the test wrong? A test asserting behavior nobody requires, or coupling to an implementation detail, gets deleted, not repaired. Delete the test, keep the behavior test.
• Broken guard, hook, lint rule, or check: does it prevent a real failure that actually happened? No evidence of a caught failure and it costs every run -> delete it. A guard that fires on correct work is worse than no guard: it trains everyone to override.
• Broken feature path nothing reaches: delete the path, not patch it.
• Machinery with a cleaner replacement already present: delete the old one in the same change.

Cut fast and hard. Do not stage a deprecation for code only this repo calls.

Repair instead of deleting only when: it is on the preservation contract; or it is the sole defense against an irreversible failure (data loss, secret leak, production destruction); or deleting it breaks a published API or another repo's contract. Name which one applies.

Every deletion is recorded: what, why it earned nothing, what now covers the case (or that nothing needs to). Deleting an item on the preservation contract is a scope cut, not a simplification, and is forbidden. </deletion_doctrine>

Project config is .ccnrc JSON:

{
  "version": 1,
  "default": 15,
  "budgets": { "src/machine.ts:transition": 20 },
  "skip": { "src/legacy-repo.ts:*": "lizard cannot enter createLegacyRepo's returned methods" }
}

Selectors are repo-relative-file:function globs. --skip 'selector=reason' is the one-run equivalent. A skip without a reason is invalid. Budgets are declared design constraints, not a way to bless today's number: name why the function earns the higher ceiling in the config diff.

Ladder (default, project config outranks it):

• 1 to 5: leave alone
• 6 to 10: refactor only if already touching
• 11 to 15: refactor now
• over 15: must split

<hard_rules>

• Preserve the destination: every requested outcome and feature remains required and reachable. Simplify architecture and execution, never the user's ambition or product scope.
• Preserve behavior that anything requires. Tests before and after. Same inputs, same outputs, same errors.
• Removal is allowed, and preferred, for duplication, dead paths, unearning guards, and machinery whose absence cannot change any contract line. "Not now," "later," "manual for the pilot," and narrower audiences/products are scope cuts when the source of truth did not already say them.
• Do not use sequencing as deletion. Later phases must still name their delivery route and acceptance condition; evidence gates may reorder work, but cannot cancel it.
• Do not game the metric. A dense one-liner hiding six branches is worse than the honest if-chain it replaced. Complexity moves into named units; it never disappears into cleverness. A CCN drop with a rising token count per line is the tell.
• Do not change public APIs or exported signatures without asking.
• One responsibility per function. If the name needs "and", split again.
• Small functions with clear names beat few functions with section comments.
• No optional finish: a manual complexity command without project verify/pre-commit wiring is incomplete.
• Never introduce the gate red on the existing default branch. Snapshot current debt, declare narrow budgets with reasons, then tighten them as functions improve.
• The verifier is a different agent than the builder. self, builder self-measure, primary lane validation, a script the builder wrote this session, and an unfilled <verifier identity> placeholder are all invalid signatures. An unsigned report is an unfinished run. </hard_rules>

ACCEPTANCE: every contract line has an equally strong delivery route; every deletion is justified under the deletion doctrine; no measured function regresses; budgets hold; the project's normal verify path runs the gate
ACCEPT WHEN: contract file checks line by line with zero removed, weakened, newly deferred, or optional outcomes; every deleted test/guard/path names what it failed to earn and what covers the case now; fresh --diff says regressed=0; project verify passes; seeded over-budget fixture makes it fail; no exported signature changed
CHECK: diff .simplify-contract.md against the source of truth and the result line by line; ${CLAUDE_PLUGIN_ROOT}/scripts/complexity.sh --diff <before.tsv> <repo>; <project verify command>; <seeded failure probe>; git diff <base-ref> --diff-filter=D --name-only; git diff <base-ref> -- <files> | grep -E '^[-+](def |export |func |pub fn )'
ESCALATE IF: any contract line lacks a route or became weaker/later/optional; a deletion removed the only defense against an irreversible failure; AST-aware JS/TS parsing is unavailable for object-literal methods; any row regresses; a skip lacks a concrete parser limitation; or a one-liner replaced a branch without a name
DISCOVERY AXIS: invariant

Builder and verifier identities go on the receipt and must differ. The builder never fills in "behavior verified".

code:

## Complexity report
Reduced: N · unchanged: N · regressed: 0 · removed: N
Deleted: <file:symbol - what it failed to earn> | none
Destination: N/N contract lines preserved · weakened/deferred/removed: 0 (.simplify-contract.md)
Budgets: <config path>; exceptions: <none | selectors + reasons>
Gate: <project verify command> (seeded red -> clean green), baseline @ <ref>
Verified by: <verifier identity, not the builder>

system:

## Simplification report
Destination: N/N contract lines preserved · weakened/deferred/removed: 0 (.simplify-contract.md)
Removed: <duplicated mechanism / dead step / unearning gate - why it earned nothing> | none
Collapsed: <what merged into what>
Sequenced: <item - later phase, its delivery route, its acceptance condition> | none
Verified by: <verifier identity, not the builder>

Keep prose minimal. Numbers and diffs do the talking.