Simplify Skill

Behavior-preserving code simplification. Reduce complexity, eliminate noise, and improve readability without changing what the code does.

When to load this skill

Load when asked to:

"Simplify this function/module"
"Reduce complexity without changing behavior"
"Clean up this code"
"Refactor for readability"
"Remove dead code / unused paths"

Core Rule: Behavior Is Invariant

Every simplification MUST preserve observable behavior:

Same inputs → same outputs
Same side effects
Same error conditions
Same public API surface

If a simplification changes behavior, it is a bug, not a simplification.

Simplification Checklist

Work through these categories in order. Stop at any category where a change risks behavior — flag it and ask before proceeding.

1. Dead Code Removal (zero-risk)

Remove imports that are never used
Remove variables assigned but never read
Remove functions/methods never called (verify with usages search)
Remove commented-out code blocks older than the last commit
Remove pass statements in non-empty bodies

Verification: Run existing tests. If they pass, the removal was safe.

2. Redundancy Elimination (low-risk)

Replace repeated literals with a named constant
Collapse duplicate conditional branches with identical bodies
Merge nested if chains into a single compound condition where intent is clearer
Remove double negations (not not x → bool(x) or just x where truthy is enough)
Replace if x == True: with if x: and if x == False: with if not x:

3. Standard Library Substitution (medium-risk — test after each)

Replace manual loop patterns with built-ins (any(), all(), sum(), min(), max())
Replace dict.get(key, None) with dict.get(key) (same default)
Replace string concatenation in loops with "".join()
Replace manual null-checks on dict access with dict.get()
Replace len(x) == 0 with not x (only for types where falsy = empty)

4. Structural Flattening (higher-risk — require test coverage before touching)

Extract repeated logic into a helper function (only if used 3+ times)
Flatten deeply nested callbacks/try-except into early returns
Convert if/elif/elif/else chains that are purely data into a lookup dict
Break functions longer than ~50 lines into focused sub-functions

5. Naming Clarity (cosmetic — no behavior risk)

Rename single-letter variables to descriptive names (except loop indices i, j, k)
Rename boolean variables to is_, has_, can_, should_ prefix
Rename functions whose name contradicts what they do

Process

1. Read the target file(s)
2. Run existing tests to establish a green baseline
   → If no tests exist: STOP and report — simplifying untested code is risky
3. Work through checklist categories 1 → 5
4. After each category: run tests again
5. If a test fails: revert the last change, flag it as unsafe, continue with next item
6. Report: what was simplified, what was skipped and why

Output Format

## Simplification Report: <file>

### Applied
- Removed 3 unused imports (F401)
- Collapsed duplicate if-branch in `process_order()` (lines 45-60)
- Replaced manual loop sum with `sum()` in `calculate_total()`

### Skipped (behavior risk)
- `legacy_path()` — called from 2 external modules not in this repo; cannot verify safely
- Nested try-except in `parse_config()` — unclear if all error paths are covered by tests

### Test Results
- Before: 47 tests passing
- After: 47 tests passing (0 regressions)

### Lines changed: 312 → 247 (-21%)

Anti-Patterns to Avoid

Temptation	Why to avoid
"This logic can be a one-liner"	One-liners can obscure intent — only collapse if clarity improves
"This variable is obvious from context"	Removing names makes debugging harder; keep them
"Dead code — just delete it"	Always verify with `search/usages` first; it may be called via reflection
"The tests are slow, I'll skip them"	You have no evidence the simplification is safe without tests
"I'll simplify and add new behavior at the same time"	Never mix simplification with feature changes in one step

Integration Notes

Agents that use this skill: Hermes (backend cleanup), Aphrodite (frontend cleanup), Talos (fast cleanup), Themis (refactor suggestions in review)
Always pair with: existing test suite. No tests = no simplification.
Scope: one file or one function at a time. Don't batch-simplify across many files in one pass.

Appendix: AI Slop Detection

Use this section to detect and eliminate AI-generated code smells from files while preserving functionality.

The Core Principle

Code should read like a senior wrote it, not an AI.

AI-generated code tends to over-explain, over-handle, and over-engineer. These patterns catch those issues and guide you to replace them with clean, concise alternatives.

AI Slop Patterns to Detect

1. Verbose Comments ❌

Comments that explain what the code already says:

# ❌ AI Slop
# This function hashes the user's password using bcrypt
# and returns the hashed password for storage in the database
def hash_password(password: str) -> str:
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt())

# ✅ Clean
def hash_password(password: str) -> str:
    """Hash password with bcrypt."""
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt())

2. Redundant Error Handling Comments ❌

Comments that describe obvious error paths:

# ❌ AI Slop
# Try to fetch the user from the database
# If the user is not found, raise a 404 error
# If there is a database error, raise a 500 error
async def get_user(user_id: str):
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(404)

# ✅ Clean
async def get_user(user_id: str):
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(404, "User not found")

3. AI Filler Phrases ❌

Generic phrases that add no value:

# ❌ AI Slop
# In this implementation, we handle the user authentication
# by checking the provided credentials against the database
# and returning a JWT token if successful

# ✅ Clean
# Authenticate user and return JWT token.

4. Over-Engineered Patterns ❌

Unnecessary abstraction for simple tasks:

# ❌ AI Slop — Factory pattern for a simple dict
class UserResponseFactory:
    @staticmethod
    def create(user: User) -> dict:
        return {"id": user.id, "email": user.email}

# ✅ Clean — Just a function
def user_response(user: User) -> dict:
    return {"id": user.id, "email": user.email}

5. Self-Congratulatory Comments ❌

Comments that praise the implementation:

# ❌ AI Slop
# This robust implementation ensures secure password handling
# with industry-standard bcrypt hashing

# ✅ Clean
# Bcrypt password hashing.

Detection Rules

Comment Analysis

A comment is flagged as AI slop if it matches ANY of these patterns:

Pattern	Example	Severity
Starts with "This function/method/class"	"This function handles..."	High
Explains what code already says	"Check if user exists" before `if user:`	High
Uses "In this implementation"	"In this implementation, we..."	High
Uses "robust/comprehensive/elegant"	"This robust solution..."	Medium
Multi-line explanation of simple code	3+ lines explaining 1-line code	Medium
Repeats function name in comment	"hash_password: hashes the password"	Low

Code Analysis

Code is flagged as over-engineered if:

Pattern	Example	Severity
Factory/Builder for simple data	Factory class for dict creation	High
Abstract base class for single impl	ABC with one subclass	Medium
Strategy pattern for 2 options	Strategy class for if/else	Medium
Decorator for single-use logic	Decorator used once	Low

Replacement Guidelines

When AI slop is detected, replace with:

AI Slop	Replace With
"This function does X"	Docstring: `"""Do X."""`
Multi-line explanation	Single-line comment or docstring
"In this implementation..."	Remove entirely
Self-congratulatory language	Remove entirely
Redundant error comments	Keep only non-obvious context

Examples: Before and After

Before (AI Slop):

# This class provides a comprehensive user management service
# that handles all CRUD operations for the User model
# with proper error handling and validation
class UserService:
    """User service for CRUD operations."""

    def __init__(self, db: AsyncSession):
        # Initialize the service with a database session
        # This allows us to perform database operations
        self.db = db

    async def create_user(self, email: str, password: str) -> User:
        # Create a new user with the provided email and password
        # First, we hash the password for security
        # Then, we create the user object and save it to the database
        # Finally, we return the created user
        hashed_pw = hash_password(password)
        user = User(email=email, password=hashed_pw)
        self.db.add(user)
        await self.db.flush()
        return user

After (Clean):

class UserService:
    """User CRUD operations."""

    def __init__(self, db: AsyncSession):
        self.db = db

    async def create_user(self, email: str, password: str) -> User:
        """Create user with hashed password."""
        user = User(email=email, password=hash_password(password))
        self.db.add(user)
        await self.db.flush()
        return user

Lines reduced: 18 → 9 (50% reduction) Readability: Significantly improved

simplify

SKILL.mdskills/simplify/SKILL.md