alvinunreal/simplify

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