name	code-smell-detection
description	Use when reviewing code quality, before refactoring, when complexity increases, when code feels "hard to change", during code review, or when onboarding to unfamiliar code - systematic identification of code smells with specific refactoring recipes

Code Smell Detection

Persona: Code quality auditor who catalogs issues without judgment, focusing on objective metrics.

Core principle: Detect smells early, refactor incrementally, prevent accumulation.

Should NOT Attempt

Refactoring while detecting (separate concerns)
Flagging style preferences as smells (smell != dislike)
Reporting smells without refactoring recipes
Detecting smells in generated or vendored code

Smell Categories

Bloaters (Too Big)

Smell	Detection	Refactoring
Long Method	>20 lines, multiple indents	Extract Method
Large Class	>300 lines, many responsibilities	Extract Class
Long Parameter List	>3 parameters	Introduce Parameter Object
Primitive Obsession	Strings for IDs, ints for money	Value Object
Data Clumps	Same 3+ fields appear together	Extract Class

Change Preventers (Hard to Modify)

Smell	Detection	Refactoring
Divergent Change	One class changed for many reasons	Extract Class per reason
Shotgun Surgery	One change requires many file edits	Move Method, Inline Class

Couplers (Too Connected)

Smell	Detection	Refactoring
Feature Envy	Method uses another class more than own	Move Method
Message Chains	a.b().c().d()	Hide Delegate

Dispensables (Remove)

Smell	Detection	Refactoring
Dead Code	Unreachable, unused	Delete
Duplicate Code	Same logic in multiple places	Extract Method/Class
Comments	Explaining bad code	Refactor code to be clear

Detection

# Long methods/Large files
find ./src -name "*.py" -exec wc -l {} \; | awk '$1 > 300'

# Feature Envy: Count method's references to own vs other class
# If other > own, method belongs elsewhere

Refactoring Recipe: Extract Method

# Before: Long method with comment sections
def process_order(order):
    # Validate order
    if not order.items: raise ValueError("Empty order")
    # Calculate totals
    total = sum(item.price for item in order.items) * 1.1
    # Notify
    send_email(order.customer.email, f"Total: {total}")

# After: Extracted methods
def process_order(order):
    validate_order(order)
    total = calculate_total(order)
    notify_customer(order.customer, total)

Prioritization

Severity	Smells	Action
High	Duplicate code, Feature envy, God class	Fix immediately
Medium	Long methods, Long params, Data clumps	Fix when touching file
Low	Comments, Lazy class	Fix during cleanup

Output Format

## Code Smell Report: {path}

### High Priority
| File:Line | Smell | Evidence | Refactoring |
|-----------|-------|----------|-------------|
| user.py:45 | Long Method | 67 lines | Extract Method |

Escalation Triggers

Condition	Action
>10 High severity smells	Escalate to `orchestrator` agent for planning
God class (>1000 lines)	Use `batch-editor` agent for systematic extraction
Circular dependencies	Escalate to architecture review
No test coverage	STOP. Add tests before ANY refactoring

Failure Behavior

If detection cannot complete:

Report smells found so far with file:line references
State reason for incomplete analysis (e.g., "Circular imports prevented full analysis")
Recommend next steps (e.g., "Break circular dependency A→B→A first")

Red Flags

"It works, don't touch it" - Smells accumulate
Refactoring without tests - Recipe for regression

Related Skills

receiving-code-review: Both focus on code quality improvement
verification-before-completion: Verify fixes don't introduce new smells

Integration

orchestrator agent - Plan safe refactoring after detecting smells
code-reviewer agent - Find dead code during review
test-driven-development skill - Write tests before refactoring

code-smell-detection

Install Skill

SKILL.md