code-simplify

SKILL.md

Code Simplify

Objective

Simplify code while preserving behavior, public contracts, and side effects. Run a full simplification pass by default: apply high-confidence simplifications that materially improve comprehension or reduce defect risk, including naming/intent cleanup when safe.

Arguments

Paths, patterns, a commit/range, or a scope phrase: used in Scope Resolution step 2.

--no-report: Skip the full user-facing report and return terse working notes for the caller.

--no-verify: Skip verification because a parent orchestrator will verify the final result separately.

Default: perform the full simplification pass, verify touched behavior, and present the full report.

Scope Resolution

Resolve scope once, then treat the result as fixed for the rest of the run.

Verify repository context: git rev-parse --git-dir. If this fails, stop and tell the user to run from a git repository.

If the request names targets — file paths/patterns, a commit/range, a natural-language subset (e.g. "the parser changes"), or a resolved-scope fenced block with one repo-relative path per line — scope is exactly those targets. Map natural-language subsets to concrete paths before continuing.

Otherwise, scope is only session-modified files: files created or edited earlier in this session. Do not include other uncommitted changes.

If there are no session-modified files, or earlier conversation history is not visible in this context, fall back to all uncommitted files, running each command once:

tracked: git diff --name-only --diff-filter=ACMR

untracked: git ls-files --others --exclude-standard

combine both lists and de-duplicate.

Exclude generated, vendored, bulk, and low-signal files from manual simplification unless explicitly requested: lockfiles, minified bundles, build outputs, generated outputs, vendored code, and large data snapshots. When excluded files are relevant to correctness, emit an optional fenced code block tagged excluded-scope, one repo-relative path or glob per line, and cover them through verification or invariant checks.

If scope resolves to zero files, report that and stop.

Emit the scope as a fenced code block tagged resolved-scope, one repo-relative path per line. The block is authoritative: do not re-run scope commands or revisit exclusions afterward.

Operating Rules

State assumptions before editing. If multiple interpretations would change the simplification or verification strategy, present them and stop for direction.

Preserve runtime behavior exactly. Keep inputs, outputs, side effects, and error behavior stable.

Prefer project conventions over personal preferences. Infer conventions from existing code, linters, formatters, and tests.

Make small, reversible edits. Every changed line should trace to the user's request, requested cleanup, or cleanup caused by your own edits.

Write the minimum code that solves the requested problem. Do not add features, single-use abstractions, speculative flexibility, or configurability the user did not request.

Clean up only your own mess: remove imports, variables, functions, and files made unused by your changes; mention pre-existing dead code in Residual Risks instead of deleting it.

Run naming-only refactors only when they create a concrete clarity or safety gain and can be safely verified.

For generated, vendored, bulk, or low-signal files, simplify the generator, schema, or contract when possible and validate outputs with invariant checks instead of hand-editing every generated row or file.

Call out uncertainty immediately when behavior may change.

Workflow

1) Determine Scope

Apply the Scope Resolution section.

Treat any excluded-scope block as outside manual simplification but inside verification planning.

2) Build a Behavior Baseline

Read surrounding context, not only changed lines.

Identify invariants that must not change:

function signatures and exported APIs

state transitions and side effects

persistence/network behavior

user-facing messages and error semantics where externally relied on

Note available verification commands (lint, tests, typecheck).

Define success criteria before editing. For multi-step work, state a brief plan where each step names its verification check.

3) Triage Simplification Opportunities

Default to no edit unless the simplification is high-confidence and materially improves comprehension, removes current-change cleanup, or reduces defect risk.

Prefer local, behavior-preserving edits over broad rewrites.

Skip no-op passes. If the scoped code is already clear enough, report that rather than churning it.

Rename identifiers or split helpers only when there is a concrete clarity or safety gain and a safe verification path. Never reshape APIs solely for taste.

4) Apply Simplification Passes

Apply the full checklist in this order:

Control flow:

Flatten deep nesting with guard clauses and early returns.

Replace nested ternaries with clearer conditionals.

Naming and intent:

Rename ambiguous identifiers when local context supports safe renaming.

Separate mixed concerns into small helpers with intent-revealing names.

Duplication:

Remove obvious duplication.

Abstract only when at least two real call sites benefit and the abstraction reduces cognitive load.

Data shaping:

Break dense transform chains into named intermediate steps when readability improves.

Keep hot-path performance characteristics stable unless improvement is explicit and measured.

Type and contract clarity:

Add or tighten type annotations when they improve readability and safety without forcing broad churn.

Preserve external interfaces unless asked to change them.

5) Enforce Safety Constraints

Do not convert sync APIs to async (or reverse) unless explicitly requested.

Do not alter error propagation strategy unless behavior remains equivalent and verified.

Do not remove logging, telemetry, guards, or retries that encode operational intent.

Do not collapse domain-specific steps into generic helpers that hide intent.

6) Verify

Skip when --no-verify is set. Otherwise verify per the Verification section below.

7) Report

Produce the Report section below.

Simplification Heuristics

Prefer explicit local variables over nested inline expressions when it reduces cognitive load.

Prefer one clear branch per condition over compact but ambiguous condition trees.

Keep function length manageable, but do not split purely for line count.

Keep comments that explain intent, invariants, or non-obvious constraints.

Remove comments that restate obvious code behavior.

Optimize for the next maintainer's comprehension time, not minimum character count.

Anti-Patterns

Do not perform speculative architecture rewrites.

Do not introduce framework-wide patterns while simplifying a small local change.

Do not replace understandable duplication with opaque utility layers.

Do not bundle unrelated cleanups into one patch.

Do not add error handling for impossible scenarios.

Do not preserve code volume for its own sake; if a simpler equivalent approach exists, use it or explain why it does not satisfy the request.

Verification

Run the narrowest checks that validate touched behavior:

formatter/lint on touched files

targeted tests for touched modules

typecheck when relevant

invariant checks for any relevant excluded-scope outputs

Run broader checks only when risk warrants it, especially when simplification touches shared contracts. Name every skipped check and why.

Report

Skip when --no-report is set; return terse working notes instead: touched scope, key simplifications, residual risks.

Use these section headings, in this order. Omit sections that do not apply — do not number them and do not leave gaps or placeholders.

Scope

Files and regions changed, plus any excluded-scope entries with the validation strategy used for them.

Simplifications

One sentence per meaningful change, focused on the readability or maintainability gain. Confirm behavior-preservation assumptions explicitly.

Verification

Commands run and outcomes, including skipped checks.

Residual Risks

One line per risk: Assumed <assumption>; if wrong, <what breaks>; check via <command or inspection>. Plain language — expand or gloss domain-specific terms. Include questions that need a user decision, phrased directly. Write None. when there are none.

Stop Conditions

Stop and ask for direction when:

simplification requires changing public API/contracts.

requirements are unclear or competing interpretations would produce materially different edits.

behavior parity cannot be confidently verified.

the code appears intentionally complex due to domain constraints.

the requested scope implies a larger redesign rather than simplification.