139 lines
4.6 KiB
Markdown
139 lines
4.6 KiB
Markdown
---
|
|
name: simplify
|
|
description: Simplifies code for clarity without changing behavior. Use for readability, maintainability, and complexity reduction after behavior is understood.
|
|
---
|
|
|
|
# Code Simplification
|
|
|
|
## Overview
|
|
|
|
Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines - it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
|
|
|
|
## When to Use
|
|
|
|
- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
|
|
- During code review when readability or complexity issues are flagged
|
|
- When you encounter deeply nested logic, long functions, or unclear names
|
|
- When refactoring code written under time pressure
|
|
- When consolidating related logic scattered across files
|
|
- After merging changes that introduced duplication or inconsistency
|
|
|
|
**When NOT to use:**
|
|
|
|
- Code is already clean and readable - don't simplify for the sake of it
|
|
- You don't understand what the code does yet - comprehend before you simplify
|
|
- The code is performance-critical and the "simpler" version would be measurably slower
|
|
- You're about to rewrite the module entirely - simplifying throwaway code wastes effort
|
|
|
|
## The Five Principles
|
|
|
|
### 1. Preserve Behavior Exactly
|
|
|
|
Don't change what the code does - only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
|
|
|
|
Before every change, ask:
|
|
|
|
- Does this produce the same output for every input?
|
|
- Does this maintain the same error behavior?
|
|
- Does this preserve the same side effects and ordering?
|
|
- Do all existing tests still pass without modification?
|
|
|
|
### 2. Follow Project Conventions
|
|
|
|
Simplification means making code more consistent with the codebase, not imposing external preferences.
|
|
|
|
Before simplifying:
|
|
|
|
1. Read `AGENTS.md` / project conventions
|
|
2. Study how neighboring code handles similar patterns
|
|
3. Match the project's style for imports, naming, function style, error handling, and type annotations
|
|
|
|
Simplification that breaks project consistency is not simplification - it's churn.
|
|
|
|
### 3. Prefer Clarity Over Cleverness
|
|
|
|
Explicit code is better than compact code when the compact version requires a mental pause to parse.
|
|
|
|
- Replace nested ternaries with readable control flow
|
|
- Replace dense inline transforms with named intermediate steps when they clarify intent
|
|
- Keep helpful names even if they cost a few extra lines
|
|
|
|
### 4. Maintain Balance
|
|
|
|
Watch for over-simplification:
|
|
|
|
- Don't inline away names that carry meaning
|
|
- Don't merge unrelated logic into one larger function
|
|
- Don't remove abstractions that serve testability or extensibility
|
|
- Don't optimize for line count over comprehension
|
|
|
|
### 5. Scope to What Changed
|
|
|
|
Default to simplifying recently modified code. Avoid unrelated drive-by refactors unless explicitly asked.
|
|
|
|
## Process
|
|
|
|
### Step 1: Understand Before Touching
|
|
|
|
Before changing or removing anything, understand why it exists.
|
|
|
|
Answer:
|
|
|
|
- What is this code's responsibility?
|
|
- What calls it? What does it call?
|
|
- What are the edge cases and error paths?
|
|
- Are there tests that define expected behavior?
|
|
- Why might it have been written this way?
|
|
|
|
If you can't answer these, read more context first.
|
|
|
|
### Step 2: Look for Simplification Opportunities
|
|
|
|
Signals:
|
|
|
|
- Deep nesting
|
|
- Long functions with mixed responsibilities
|
|
- Nested ternaries
|
|
- Boolean flag arguments
|
|
- Repeated conditionals
|
|
- Generic or misleading names
|
|
- Duplicated logic
|
|
- Dead code
|
|
- Wrappers or abstractions that add no value
|
|
|
|
### Step 3: Apply Changes Incrementally
|
|
|
|
Make one simplification at a time.
|
|
|
|
For each simplification:
|
|
|
|
1. Make the change
|
|
2. Run relevant tests
|
|
3. Keep it only if behavior is preserved
|
|
|
|
Separate refactoring from feature work whenever possible.
|
|
|
|
### Step 4: Verify the Result
|
|
|
|
After simplifying, confirm:
|
|
|
|
- The code is genuinely easier to understand
|
|
- The diff is clean and reviewable
|
|
- Project conventions still match
|
|
- No behavior, error handling, or side effects changed
|
|
|
|
## Guidance for This Repository
|
|
|
|
- Prefer straightforward TypeScript over clever compression
|
|
- Preserve existing runtime behavior, tests, and hooks
|
|
- Favor explicit names and smaller focused helpers when they improve readability
|
|
- Keep refactors tightly scoped to the task or review feedback
|
|
|
|
## Verification Checklist
|
|
|
|
- [ ] Existing tests pass without modification
|
|
- [ ] Build/typecheck/lint still pass
|
|
- [ ] No unrelated files were refactored
|
|
- [ ] No error handling was weakened or removed
|
|
- [ ] The result is simpler to review than the original
|