Simplifier

Analyze recently modified Python code and apply refinements that enhance clarity, consistency, and maintainability while preserving exact functionality. Prioritize readable, explicit code over overly compact solutions.

When to Use This Skill

Use when:

• Code has been recently modified and needs polish
• Reviewing code for clarity and consistency improvements
• Reducing complexity or nesting depth
• Ensuring project standards are applied to changed code

Don't use when:

• Running a full project audit (use /audit instead)
• Writing new features or fixing bugs (use relevant skills)
• Code hasn't been modified recently (unless explicitly asked)

1. Preserve Functionality

Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.

2. Apply Project Standards

Follow the conventions skill standards (summary below for reference):

• Imports: Absolute imports, sorted (stdlib → third-party → local)
• Type hints: Complete annotations on all function signatures
• Docstrings: Google-style for all public functions and classes
• Naming: Explicit names (file_count not fc), ALL_CAPS for constants
• Logging: Never print() - always use logger from ${PROJECT_NAME}.core
• Error handling: Specific exceptions, exc_info=True for logging
• Line length: 88 characters (Ruff default)
• Python version: 3.13+ features (use | for unions, built-in generics)

3. Enhance Clarity

Simplify code structure by:

• Reducing nesting: Flatten deeply nested code with early returns
• Eliminating redundancy: Remove duplicate logic and dead code
• Improving names: Use descriptive, explicit variable and function names
• Consolidating logic: Group related operations together
• Removing obvious comments: Code should be self-documenting
• Avoiding nested ternaries: Prefer if/elif/else or match statements
• Choosing clarity over brevity: Explicit code > clever one-liners

Simplification Patterns

Before - Nested conditionals:

def process(data):
    if data:
        if data.is_valid:
            if data.status == "active":
                return handle(data)
    return None

After - Early returns:

def process(data: Data | None) -> Result | None:
    if not data:
        return None
    if not data.is_valid:
        return None
    if data.status != "active":
        return None
    return handle(data)

Before - Redundant else:

def get_status(value):
    if value > 0:
        return "positive"
    else:
        return "non-positive"

After - No else after return:

def get_status(value: int) -> str:
    if value > 0:
        return "positive"
    return "non-positive"

Before - Complex comprehension:

result = [transform(x) for x in items if x is not None and x.valid and x.status == "active"]

After - Explicit loop or split:

active_items = (x for x in items if x is not None and x.valid)
result = [transform(x) for x in active_items if x.status == "active"]

Before - Nested ternary:

status = "high" if value > 100 else "medium" if value > 50 else "low"

After - Match or if/elif:

match value:
    case v if v > 100:
        status = "high"
    case v if v > 50:
        status = "medium"
    case _:
        status = "low"

4. Maintain Balance

Avoid over-simplification that could:

• Reduce code clarity or maintainability
• Create overly clever solutions that are hard to understand
• Combine too many concerns into single functions (keep single responsibility)
• Remove helpful abstractions that improve code organization
• Prioritize "fewer lines" over readability
• Make the code harder to debug, test, or extend
• Break type safety or lose type information

Keep These Patterns

• Dataclasses/Pydantic models for structured data
• Context managers for resource handling
• Generators for large data processing
• Type aliases for complex types
• Helper functions that improve testability
• Constants at module level for magic values

5. Focus Scope

Only refine code that has been recently modified or touched in the current session, unless explicitly instructed to review a broader scope.

Refinement Process

1. Identify recently modified code sections
2. Analyze for opportunities to improve clarity and consistency
3. Verify type hints are complete and correct
4. Apply project-specific Python standards
5. Run checks to ensure code passes:
   • uv run ruff check .
   • uv run pyright
6. Ensure all functionality remains unchanged
7. Document only significant changes that affect understanding

Quality Checklist

After simplification, verify:

• All type hints present and accurate
• Google-style docstrings on public APIs
• No print() statements (use logger)
• No bare except: clauses
• No nested ternaries
• No magic numbers (use constants)
• Early returns reduce nesting
• Functions have single responsibility
• ruff check passes
• pyright passes
• All tests pass

Output Format

When simplifying code, report:

## Simplification Report

### Files Modified
- path/to/file.py

### Changes Applied
1. Flattened nested conditionals in `process_data()` using early returns
2. Added type hints to `calculate_total()`
3. Replaced print() with logger.info()
4. Extracted magic number 86400 to `SECONDS_PER_DAY` constant

### Verification
- [x] ruff check passes
- [x] pyright passes
- [x] All tests pass

### Functionality
No behavioral changes - all original functionality preserved.

See Also

• conventions — coding standards this skill applies
• /audit — full project audit