Skip to content
Skills Library
Programming · Building & coding

ia-simplifying-code

/ia-simplifying-code

Simplifies, polishes, and declutters code without changing behavior. Use when asked to simplify, clean up, refactor, declutter, remove dead code or AI slop, or improve readability, including analysis-only simplification reports and code pasted inline.

Repository
whetstone ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Simplifies, polishes, and declutters code without changing behavior. Use when asked to simplify, clean up, refactor, declutter, remove dead code or AI slop, or improve readability, including analysis-only simplification reports and code pasted inline.

Original author description

Simplifies, polishes, and declutters code without changing behavior. Use when asked to simplify, clean up, refactor, declutter, remove dead code or AI slop, or improve readability, including analysis-only simplification reports and code pasted inline.

How it works

  1. Working rules
  2. Principles
  3. Process
  4. Stop Conditions
  5. Constraints
  6. Verify
  7. Output
  8. Task-specific references
Original SKILL.md headings · 86 lines, 1,248 words
SKILL.md preview
---
name: ia-simplifying-code
class: discipline
description: >-
  Simplifies, polishes, and declutters code without changing behavior. Use when
  asked to simplify, clean up, refactor, declutter, remove dead code or AI slop,
  or improve readability, including analysis-only simplification reports and
  code pasted inline.
---

# Simplifying Code

## Working rules

- Preserve behavior, interfaces, side effects, and domain intent; prove any unshipped-shape exception has no consumers outside scope.
- Before removing a guard for an external hazard, reproduce its precondition and show the hazard is handled; otherwise retain it.
- Verify standard-library substitutions on empty, null, no-match, ordering, and zero-value cases.
- For analysis-only requests, identify targets and report proposed simplifications without editing code.

## Principles

| Principle | Rule |
|-----------|------|
| **Preserve behavior** | Output must do exactly what the input did, with no silent feature additions or removals. Specifically preserve: async/sync boundaries (do not convert sync to async or reverse), error propagation paths (do not alter strategy), logging/telemetry/guards/retries that encode operational intent, and domain-specific steps (do not collapse into generic helpers that hide intent). One carve-out: a shape that existed only in an earlier iteration of the current unshipped scope is not protected behavior. Verify it has no deployed, persisted, public, external, dependent-branch, or in-repo caller outside the resolved scope, and that every required caller update fits inside the edit boundary; otherwise keep the compatibility path. This narrow exemption is about shapes with provably zero consumers; it never licenses removing a guard, which is governed by the evidence bar under AI Slop Removal |
| **Explicit over clever** | Prefer explicit variables over nested expressions. Readable beats compact |
| **Simplicity over cleanliness** | Prefer straightforward code over pattern-heavy "clean" code. Three similar lines beat a premature abstraction |
| **Surgical changes** | Touch only what needs simplifying. Match existing style, naming conventions, and formatting of the surrounding code |
| **Surface assumptions** | Before changing a block, identify what imports it, what it imports, and what tests cover it. Edit dependents in the same pass |
| **Delete before simplifying** | Prefer deletion over simplification, simplification over optimization, and optimization over automation. A pass that finds nothing to change is a valid, complete result |

Changing an interface, exported name, persisted format, or path reaches past the import graph. Enumerate the producers, consumers, schemas, fixtures, generators, manifests, scripts and CI recipes, config references, and documents that carry the old identifier, and migrate them in the same pass. Close out by searching for the old identifier: zero hits, or one line accounting for each intentional remainder. Renames rot in the fixture holding the old key and the `.env.example` entry, neither of which any import graph contains. When the identifier is a public or exported API, Stop Conditions applies first: confirm with the user, then enumerate; the sweep runs unprompted only for internal identifiers.


## Process

1. **Read first**: understand the full file and its dependents before changing anything. Apply Chesterton's Fence: when code looks unnecessary but its reason is unclear, check `git blame` before removing it. First understand the reason, then decide if the reason still applies.
2. **Identify invariants**: what must stay the same? Public API, return types, side effects, error behavior. Before editing, capture relevant observable outputs from a throwaway worktree representing the exact pre-edit state; a pre-change ref suffices only if it matches that state. Preserve relevant existing uncommitted edits in the baseline copy without stashing the working tree.
3. **Identify targets**: find the highest-impact simplification opportunities. Impact = readability and maintainability; prioritize: control flow -> naming -> duplication -> data shaping -> types (see Smell -> Fix table)
4. **Apply in order**: control flow → naming → duplication → data shaping → types. Structural changes first, cosmetic last. For analysis-only requests, describe the proposed changes instead of applying them.
5. **Verify**: for applied changes, confirm behavior parity with relevant tests, type checks, and import checks. Compare responses, CLI output and exit status, or job artifacts against the pre-edit captures under identical inputs. Normalize only documented nondeterministic fields consistently on both sides; treat unexplained differences as regressions. Use direct comparison when tests are absent, while naming unobserved behavior. For analysis-only reports, identify the required checks and available evidence without claiming that proposed changes passed verification.
6. **Pre-submit scope audit**: walk every changed line and ask "does the requested task explicitly require this line?" If no, revert it and list it as a follow-up under Residual Risks. For the pre-edit complement on ambiguous-scope requests ("simplify my project"), see `ia-verification-before-completion`'s Scope Confirmation gate.


## Stop Conditions

Stop and ask before proceeding when:
- Simplification requires changing a public API (function signatures, return types, exports)
- Behavior parity cannot be verified through tests or a direct baseline comparison
- Code is intentionally complex for domain reasons (performance-critical, protocol compliance)
- Scope implies a redesign rather than a simplification


## Constraints

- Only simplify what was requested; do not add features, expand scope, introduce new dependencies, or add speculative configurability or flexibility the request did not ask for
- Leave unchanged code untouched; do not add comments, docstrings, or type annotations to lines that were not simplified
- Do not bundle unrelated cleanups into one patch; each simplification should be a coherent, reviewable unit
- Do not introduce framework-wide patterns while simplifying a small local change
- Do not replace understandable duplication with opaque utility layers; three similar lines are better than a premature abstraction
- Keep comments that explain intent, invariants, or non-obvious constraints, and tool directives ([carve-outs](./references/simplification-patterns.md)). Remove comments that restate obvious code behavior. Fix stale comments only on lines this pass touches.
- If a simplification would make the code harder to understand, skip it
- Watch for over-simplification: inlining too aggressively removes names that gave concepts meaning; combining unrelated logic into one function hides distinct responsibilities; removing abstractions that exist for testability breaks the test suite
- Before deleting apparently dead code, search the whole tree, including tests, fixtures, config, templates, and string-keyed or dynamic callers. If the search cannot detect the relevant dispatch mechanism, retain the code and ask instead of treating zero hits as proof
- For artifacts whose value is self-containment (prompts, skill and agent instructions, per-service configuration, vendored policy files), duplication is cheaper than a shared dependency until edits actually drift. Extract only after coordinated changes have repeatedly gone out of sync, or a real consumer of the shared form exists


## Verify

For analysis-only reports, distinguish available evidence from checks required after implementation. Apply the following checks after code changes:

- Tests pass and types check after changes
- No behavior change (same inputs produce same outputs)
- Scope limited to requested files; no drive-by cleanups
- Match test scope to the importer count surfaced in step 1 (Surface assumptions). Zero external importers: scoped tests on the changed paths. One or more external importers, or shared/utility code edited: run tests covering each importer. Run the full suite when the test runner has no path-scoping mechanism.


## Output

For analysis-only requests, report each target's location, proposed change, rationale, behavior risk, and required verification. Label proposals as unimplemented.

For code pasted inline with no file path, return the revised snippet and a brief note of what changed instead of editing files.

After applying simplifications, report:
- **Scope touched**: files and functions modified
- **Key simplifications**: what changed and why (one line each)
- **Verification**: tests pass, types check, no behavior change
- **Residual risks**: assumptions made, areas not touched that may need attention

## Task-specific references

Read the relevant reference before implementing or reviewing the matching behavior:

- For identifying smells, removing AI-generated clutter, or eliminating a guard or workaround: [simplification-patterns.md](./references/simplification-patterns.md).
- When chained with other skills on a shared resolved scope: [orchestrated-simplification.md](./references/orchestrated-simplification.md).
Files in this package (4)
  • SKILL.md 9 KB
  • SPEC.md 4 KB
  • references/orchestrated-simplification.md 2 KB
  • references/simplification-patterns.md 5 KB

Versions

The database has no other skills named ia-simplifying-code.

Database snapshot: 13.11.2026 · package version 653725ea14ec (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100simplifying-code
    Simplifies, polishes, and declutters code without changing behavior. Use when asked to simplify, clean up, refactor, declutter, remove dead code or AI slop, or improve readability, including analysis-only simplification reports.
  • 90simplifying-code
    Simplifies, polishes, and declutters code without changing behavior. Use when asked to "simplify code", "clean up code", "polish code", "refactor", "declutter", "reduce complexity", "remove dead code", "remove AI slop", "improve readability", or "tighten up this file".
  • 86simplify
    Use when the user asks to simplify, clean up or refactor recently changed code without changing what it does (duplication, dead code, needless complexity).
  • 100refactor-clean
    Use when code has grown complex, duplicated, or cluttered — clean up structure and remove dead code without changing observable behavior
  • 100code-simplification
    Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. Use when asked to simplify, clean…
  • 90improve
    Makes existing code easier to understand without changing behavior. Use to simplify structure, remove duplication or dead code, improve names, or remove unnecessary abstractions.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.