Code Simplification

Code Simplification

> Adapted from addyosmani/agent-skills under the MIT License. Copyright (c) Addy Osmani. Modifications by kaijutsu maintainers — composed with polish and blunder-hunt.

Goal: smaller code, same behavior. The deliverable is a diff that reduces LOC, removes abstractions that earn nothing, and consolidates near-duplicates.

When to invoke

• A file is over 500 lines
• A module's surface has more functions than it has callers per function
• Duplicate logic spotted in 2+ places
• User says "this feels overengineered" or "clean this up"

Process

Step 1: Read before deleting (Chesterton's Fence)

For every candidate removal, ask:

• Why is this here? Find the original commit (git log -p ) and read the message.
• Who calls it? grep -r '' or use LSP find-references.
• What test covers it?

If you can't answer all three, DO NOT remove it. The fence exists for a reason; first understand the reason, then decide.

Step 2: Find candidates

• Dead code: unreferenced exports, unreachable branches, unused imports
• Duplicate logic: 2+ functions doing the same thing with minor variations
• Premature abstraction: a base class / generic with one concrete subclass / instance
• Leaky helper: a util that exposes implementation details its only caller could inline
• File-over-500: split by cohesion (related functions stay together; orthogonal concerns split out)

Step 3: Apply Rule of 500

If a single file exceeds 500 LOC:

1. Identify cohesion clusters within the file
2. Split into 2-3 files of DRY. Tests benefit from descriptiveness over de-duplication. Check each candidate for actual cost-of-duplication vs cost-of-abstraction. |

| "The file is too big" | Length isn't always the right metric — cohesion is. A 600-LOC file with one focused concern beats two 300-LOC files with split-brain logic. |

Hard rules

• Never delete what you don't understand. Read the commit history first.
• Behavior-preserving means tests pass. If your "simplification" changes behavior, it's a refactor — different skill.
• Public APIs are sacred unless the user explicitly requested a breaking change.
• One simplification per PR. Multiple unrelated cleanups in one PR = unreviewable.
• Compose blunder-hunt AND polish before declaring done.

Composes

• polish — review-and-fix loop after the simplification
• blunder-hunt — regression-risk lens

When NOT to use

• Code you've never read before in a domain you don't understand (read first, simplify later)
• Code under active feature development (wait until the feature lands)
• Code with no tests (write tests first, then simplify)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: momentmaker
• Source: momentmaker/kaijutsu
• License: MIT
• Homepage: https://kaijutsu.dev/

Install and usage instructions live in the source repository linked above.