simplify-code
Simplify recently changed code for clarity and maintainability while preserving behavior. Use when the user says "simplify", "simplify code", "make this simpler", "clean up", or after implementing a logical chunk.
When & Why to Use This Skill
The 'simplify-code' skill is a specialized developer tool designed to enhance code quality by reducing complexity and improving maintainability. It intelligently analyzes recently modified code to flatten control flows, eliminate redundancies, and clarify logic while strictly preserving original behavior and API integrity. By prioritizing readability over mere brevity, it helps developers transform 'clever' or messy implementations into clean, professional-grade code that is easy for teams to understand and support.
Use Cases
- Pre-PR Refactoring: Automatically clean up complex logic and remove redundant code in recently modified files before submitting a Pull Request.
- Reducing Cognitive Load: Transform deeply nested if-else structures into linear guard clauses to make the code easier to read sequentially.
- Technical Debt Cleanup: Identify and eliminate dead code, unused variables, or unreachable branches in active development branches.
- Standardizing Logic: Align newly written code with best practices for clarity, ensuring that the intent of the structure is obvious without excessive commenting.
- Post-Implementation Polishing: Use after a rapid prototyping session to 'professionalize' the code structure while ensuring all side effects and error paths remain unchanged.
| name | simplify-code |
|---|---|
| description | Simplifies code for clarity and maintainability while preserving exact behavior. Focuses on recently modified code. Use when user says "simplify", "simplify code", "make this simpler", "clean up", or "refactor for clarity". |
| compatibility | Requires filesystem read/write access. Uses git if available to scope changes. Language-agnostic. |
Simplify Code
Reduce unnecessary complexity while preserving exact functionality. Prioritize clarity and maintainability over brevity.
Philosophy
Simple code is not short code. Simplicity means:
- Easy to read sequentially without mental backtracking
- Intent is obvious from structure, not comments
- Each function/block does one thing
- Control flow is linear where possible
- No cleverness that requires explanation
Compression that hurts readability is not simplification.
Scope
Default scope: recently modified code in the current session.
To identify scope:
- Check staged changes:
git diff --staged - Fall back to unstaged:
git diff - Use user-provided file paths if specified
Do not perform broad refactors (cross-file renames, architecture changes) unless explicitly requested.
Process
1. Identify Target Code
git diff --staged --name-only # or git diff --name-only
Read the modified files. Focus only on changed sections and their immediate context.
2. Establish Constraints
Before making changes, confirm these preservation requirements:
- Behavior: All outputs, side effects, and observable behavior unchanged
- API surface: Public functions, exports, and interfaces unchanged
- Error handling: All error paths and messages preserved
- Performance: No algorithmic complexity regressions
If unsure whether a change preserves behavior, do not make it.
3. Apply Simplifications
Work through the code applying transformations in priority order. Open SIMPLIFICATION-GUIDE.md for detailed heuristics.
Priority order (highest first):
- Flatten control flow: Guard clauses, early returns, reduce nesting depth
- Remove redundancy: Dead code, duplicate logic, unused variables, unreachable branches
- Clarify names: Rename only within the modified surface area
- Decompose: Split functions only when it reduces cognitive load
- Normalize patterns: Align with existing conventions (check AGENTS.md if present)
4. Avoid Anti-Patterns
Do not introduce:
- Nested ternaries (use if/else or early returns)
- Dense one-liners that hide control flow
- Abstractions that exist only to reduce line count
- Clever solutions that require explanation
- Changes outside the touched surface area
See SIMPLIFICATION-GUIDE.md for detailed anti-patterns.
5. Validate
- Run the narrowest available test/check for the modified area
- Review the diff to confirm only intended changes
- Verify no new dependencies or imports added unnecessarily
6. Report
Summarize what changed and why it's simpler.
Output Format
After completing simplification, provide:
## Simplification Summary
**Scope**: {files or areas modified}
### Changes Made
- {Change 1}: {what was done and why it's simpler}
- {Change 2}: {what was done and why it's simpler}
- ...
### Why Simpler
- {Reduced nesting from N to M levels}
- {Eliminated N lines of duplicate logic}
- {Clearer control flow via guard clauses}
### Preserved
- {Confirm behavior unchanged}
- {Confirm API unchanged}
- {Note any intentional complexity retained and why}
### Verification
- {Tests/checks run, or "none available"}
- {Diff reviewed: yes/no}
Guidelines
- Preserve first: When in doubt, don't change it
- Small changes: Multiple small improvements > one large rewrite
- Explain tradeoffs: If you leave complexity in place, note why
- Local conventions: Follow patterns already in the codebase (check AGENTS.md)
- No feature creep: Simplification is not the time to add functionality