# Simplifier

> Simplifies and refines Python code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.

- Skill: `mesca/simplifier` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mesca/simplifier`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mesca/simplifier/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mesca (https://skillmd.com/u/mesca)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/mesca/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:**
```python
def process(data):
    if data:
        if data.is_valid:
            if data.status == "active":
                return handle(data)
    return None
```

**After - Early returns:**
```python
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:**
```python
def get_status(value):
    if value > 0:
        return "positive"
    else:
        return "non-positive"
```

**After - No else after return:**
```python
def get_status(value: int) -> str:
    if value > 0:
        return "positive"
    return "non-positive"
```

**Before - Complex comprehension:**
```python
result = [transform(x) for x in items if x is not None and x.valid and x.status == "active"]
```

**After - Explicit loop or split:**
```python
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:**
```python
status = "high" if value > 100 else "medium" if value > 50 else "low"
```

**After - Match or if/elif:**
```python
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