code-simplification

Code Simplification

Overview

Simplicity is about comprehension speed, not line count. Simple code is code another developer can read and understand quickly. This skill guides incremental simplification — making code easier to understand without changing what it does.

When to Use

• Code is harder to understand than its logic warrants
• Functions exceed ~40 lines or have deep nesting
• After a feature is working and tested (simplify, don't rewrite)
• During code review when readability is flagged

Don't simplify when:

• Code is already clean and conventional
• You don't fully understand what the code does (Chesterton's Fence)
• The code is performance-critical and structured for speed
• A rewrite is already planned

Core Principles

1. Preserve Behavior Exactly — simplification changes form, not function
2. Follow Project Conventions — match existing patterns, don't introduce new styles
3. Prefer Clarity Over Cleverness — readable beats concise
4. Maintain Balance — don't over-abstract or under-abstract
5. Scope Appropriately — simplify what was asked, nothing more

Core Process

Step 1: Understand (Chesterton's Fence)

1. Read the code and its tests — understand what it does and why
2. Check git blame — understand the history of complex sections
3. Identify the author's intent — is complexity intentional (performance, platform workaround)?
4. Respect /* simplify-ignore-start */ blocks — skip annotated sections

Step 2: Identify Opportunities

1. Scan for these patterns:

Pattern	Kotlin Simplification
Deep nesting	Early returns / when expressions
Long functions	Extract well-named private functions
Complex conditionals	when expression or sealed class
Nullable chains	?.let { }, ?:, safe calls
Manual null checks	requireNotNull(), checkNotNull()
Mutable state	val over var, immutable collections
Callback nesting	Coroutines / Flow
Builder patterns	Kotlin DSL or apply/also
Type casting chains	is smart casts, sealed hierarchies
Manual resource management	use { } or withContext