/code-smell - Code Smell Detector

What this is for

Structural code smells indicate design problems that make the codebase hard to change, understand, or extend. This skill scans for 10 smell families, quantifies each finding with metrics, and validates them against code context for actionable, evidence-based refactoring proposals.

Detects 10 code smell families in a target directory. Produces a structured report with metrics, evidence, and LLM-based validation of each finding.

Usage

/code-smell              # interactive (prompts for directory)
/code-smell <dir>        # scan directory directly
/code-smell -help       # show usage

PROTECTION RULE - never ~/.claude/

Read-only skill. Guard required if write mode added later.

## What You Must Do When Invoked

During analysis, assign a confidence level to each finding: proven (confirmed by evidence), likely (strong signal, needs review), or suspected (weak signal).

Step 1

1. -help / -h → print usage, exit 0.

Step 2

2. Confirm target directory exists.

Step 3

3. Run scripts/smell-scan.ps1 -ProjectDir <dir>.

Step 4

4. LLM reads the JSON output, validates each finding against the code context,

Step 5

assigns confidence, and suggests a refactoring path.

Step 6

5. Write code-smell-report.md to the working directory.

Supported Smell Families

#	Smell	Severity	Metric
1	Long method	medium	>30 executable lines
2	Deep nesting	medium	>4 indentation levels
3	God class	high	>300 lines, >10 methods, low cohesion
4	Feature envy	medium	more external than internal symbol references
5	Primitive obsession	low	repeated primitive type parameters
6	Data clump	medium	same 3+ parameters repeated across methods
7	Shotgun surgery	high	single concept scattered across many files
8	Message chain	low	a.b.c.d().e() style chains
9	Refused bequest	medium	subclass ignores inherited members
10	Speculative generality	low	unused abstract classes/interfaces

Output

code-smell-report.md with:

• Executive summary (total findings, severity breakdown)
• Detailed findings per smell family (id, file, line, metric, confidence, suggestion)
• False positives section (rejected by LLM analysis)