Simplify

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

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:

Code Analysis

Code is flagged as over-engineered if:

Replacement Guidelines

When AI slop is detected, replace with:

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