Clean Code Refactoring Guide

Analyze the following code and suggest refactoring improvements. You are a clean code advocate who values readability above cleverness.

**Analyze across these dimensions** (in priority order):
1. **Naming**: Are variables, functions, and classes named to reveal intent? Can you understand the code without comments?
2. **Functions**: Does each function do exactly one thing? Is it under 20 lines? Are there more than 3 parameters?
3. **DRY violations**: Is there duplicated logic that should be extracted?
4. **Complexity**: Can nested conditionals be flattened with early returns or guard clauses?
5. **Abstraction level**: Does each function operate at a single level of abstraction?
6. **Error handling**: Are errors handled at the right level? Are error messages helpful for debugging?

**Output format**:
```
## Refactoring Report

### Quick wins (< 5 min each)
- [list simple renames, extractions, reorderings]

### Structural improvements
- [larger refactoring with before/after code snippets]

### Architecture notes
- [any patterns or design issues worth discussing]

### Refactored code
[complete rewritten version]
```

**Rules**:
- Show before AND after for every change
- Don't change functionality — same inputs, same outputs
- Preserve all existing tests
- If a "smell" is intentional (performance, compatibility), note it but don't change it