simplify

Simplify Skill

Review recently changed files for code reuse, quality, and efficiency issues, then fix them.

Critical Importance

Simplifying code is critical for long-term maintainability. Complexity is the enemy of reliability. Every unnecessary abstraction, duplicated logic, or convoluted control flow increases the surface area for bugs and the cognitive load on every developer who reads the code. Simplification isn't about making code "prettier" — it's about making it correct, efficient, and understandable. The best code is the code you don't need to write.

The Challenge

The simplify code without losing functionality or introducing regressions, but if you can:

• Future developers will understand the code in seconds, not minutes
• Bugs will hide in fewer places
• Performance will improve naturally
• Tests will be easier to write and maintain

The challenge is removing complexity without removing capability. Can you find the perfect balance between minimal and complete?

Workflow

Step 1: Identify Changes

Find recently changed files:

git diff --stat HEAD~1          # Files changed in last commit
git diff --stat HEAD~3          # Files changed in last 3 commits
git diff --name-only            # Unstaged changes
git diff --cached --name-only   # Staged changes

If no git history is available, review files passed as arguments or ask the user which files to review.

Step 2: Spawn Three Review Agents (Parallel)

Launch these agents concurrently for comprehensive coverage:

Agent	Focus	What It Finds
Code Reuse	Duplication	Repeated logic, extractable functions, missed abstractions, copy-paste patterns
Quality	Complexity	Unnecessary complexity, dead code, poor naming, missing error handling, deep nesting
Efficiency	Performance	Redundant allocations, unnecessary iterations, missing caches, O(n²) when O(n) possible

Each agent should:

1. Read the changed files
2. Analyze against their focus area
3. Return a structured list of findings with file:line references

Step 3: Aggregate Findings

Deduplicate and prioritize findings:

1. Combine findings from all three agents
2. Remove duplicates (same issue found by multiple agents)
3. Sort by impact: bugs > performance > readability > style
4. Group related changes together

Step 4: Apply Fixes

For each finding:

1. Make the change
2. Verify the change preserves behavior
3. Run the project's linter/type checker if available
4. Ensure tests still pass

Step 5: Verify

Detect the project's build system and run the appropriate verification commands. Check package.json, Makefile, Cargo.toml, pyproject.toml, go.mod, or pom.xml to determine the toolchain, then run:

# For any project: check what's available, then run accordingly
make check          # if Makefile exists
./gradlew check     # if Gradle project
mvn verify          # if Maven project
go test ./...       # if Go project
cargo test          # if Rust project
pytest              # if Python project
ruff check .        # if Python with ruff
npm test            # if Node.js project

Do not assume a specific runtime. Discover the toolchain from project files first.

Focus Areas

Pass a focus argument to narrow scope:

/ai-eng-simplify focus on memory efficiency
/ai-eng-simplify focus on readability
/ai-eng-simplify focus on reducing duplication
/ai-eng-simplify focus on performance
/ai-eng-simplify focus on error handling

When a focus area is specified, weight findings from the matching agent higher.

What to Simplify

Code Reuse Patterns

• Duplicated logic: Extract into shared functions
• Copy-paste blocks: Parameterize differences, extract commonalities
• Similar conditionals: Merge with shared logic
• Repeated type definitions: Use generics or shared interfaces

Quality Patterns

• Deep nesting: Extract early returns, use guard clauses
• Long functions: Extract focused sub-functions
• Poor naming: Rename for clarity (variables, functions, files)
• Dead code: Remove unused imports, functions, variables
• Missing error handling: Add try/catch, validate inputs

Efficiency Patterns

• Redundant iterations: Combine loops, use map/filter/reduce
• Unnecessary allocations: Reuse objects, use primitives
• Missing caches: Memoize expensive computations
• Inefficient data structures: Use Set/Map instead of array scans
• N+1 queries: Batch database calls

What NOT to Simplify

• Intentional complexity: Some problems are inherently complex
• Performance-critical paths: Don't simplify at the cost of speed
• Public APIs: Don't change interfaces without migration plan
• Test code: Clarity over brevity in tests
• Generated code: Don't modify generated files

Confidence Assessment

After completing simplification, rate your confidence from 0.0 to 1.0:

• 0.8-1.0: All changes verified, tests pass, linter clean, no behavior changes
• 0.5-0.8: Most changes verified, some edge cases uncertain
• 0.2-0.5: Changes applied but verification incomplete
• 0.0-0.2: Changes applied without verification, regression risk high

Quality Checklist

Before finalizing:

• All findings from three agents reviewed
• Duplicates removed and findings prioritized
• Each change preserves original behavior
• Linter and type checker pass
• Tests pass (or failures are pre-existing)
• No public API changes without migration
• Confidence rated honestly

Integration with ai-eng-system

Works with the spec-driven workflow:

# After completing a feature
/ai-eng/work "implement feature X"

# Simplify the result
/ai-eng/simplify

# Or with focus
/ai-eng/simplify focus on performance

Can also be combined with /ai-eng/review for comprehensive analysis:

/ai-eng/simplify
/ai-eng/review    # Deeper review of simplified code

See Also

• text-cleanup — For removing AI-generated verbosity (different from code simplification)
• code-review — For comprehensive multi-dimensional code review
• ralph-wiggum — For iterative fix-until-green loops