code-smells-audit

Files (62)

• SKILL.md
• openai.yaml · agents/
• ATTRIBUTION.md · references/
• index.md · references/
• refactoring-names.md · references/
• afraid-to-fail.md · references/smells/
• alternative-classes-with-different-interfaces.md · references/smells/
• base-class-depends-on-subclass.md · references/smells/
• binary-operator-in-name.md · references/smells/
• boolean-blindness.md · references/smells/
• callback-hell.md · references/smells/
• clever-code.md · references/smells/
• combinatorial-explosion.md · references/smells/
• complicated-boolean-expression.md · references/smells/
• complicated-regex-expression.md · references/smells/
• conditional-complexity.md · references/smells/
• data-clump.md · references/smells/
• dead-code.md · references/smells/
• divergent-change.md · references/smells/
• dubious-abstraction.md · references/smells/
• duplicated-code.md · references/smells/
• fallacious-comment.md · references/smells/
• fallacious-method-name.md · references/smells/
• fate-over-action.md · references/smells/
• feature-envy.md · references/smells/
• flag-argument.md · references/smells/
• global-data.md · references/smells/
• hidden-dependencies.md · references/smells/
• imperative-loops.md · references/smells/
• inappropriate-static.md · references/smells/
• incomplete-library-class.md · references/smells/
• inconsistent-names.md · references/smells/
• inconsistent-style.md · references/smells/
• indecent-exposure.md · references/smells/
• insider-trading.md · references/smells/
• large-class.md · references/smells/
• lazy-element.md · references/smells/
• long-method.md · references/smells/
• long-parameter-list.md · references/smells/
• magic-number.md · references/smells/
• message-chain.md · references/smells/
• middle-man.md · references/smells/
• mutable-data.md · references/smells/
• null-check.md · references/smells/
• obscured-intent.md · references/smells/
• oddball-solution.md · references/smells/
• parallel-inheritance-hierarchies.md · references/smells/
• primitive-obsession.md · references/smells/
• refused-bequest.md · references/smells/
• required-setup-or-teardown-code.md · references/smells/
• shotgun-surgery.md · references/smells/
• side-effects.md · references/smells/
• special-case.md · references/smells/
• speculative-generality.md · references/smells/
• status-variable.md · references/smells/
• temporary-field.md · references/smells/
• tramp-data.md · references/smells/
• type-embedded-in-name.md · references/smells/
• uncommunicative-name.md · references/smells/
• vertical-separation.md · references/smells/
• …and 2 more

SKILL.md (first lines)

# Code Smells Audit

Catalog-driven smell detection: instead of ad-hoc reviewer memory, findings are
matched against 56 distilled reference cards derived from Marcel Jerzyk's
[Code Smells Catalog](https://codesmells.org/) and verified against each
smell's actual definition before they reach the report.

## Workflow

Four steps, in order: resolve the target, sweep it lens by lens, verify every
candidate against its card, write the ranked report.

### 1. Resolve the target

The argument decides scope:

| Argument | Scope |
|---|---|
| a path | that file or directory, recursively |
| a glob | files matching it |
| `diff` | the current branch's changes: files listed by `git diff --name-only $(git merge-base <default-branch> HEAD)` plus uncommitted changes (`git status --porcelain`), audit only those files, and only their changed regions when judging severity |
| *(none)* | whole-repo sweep |

Always exclude dependencies and generated code: `vendor/`, `node_modules/`,
lock files, build output, and anything the repo's `.gitignore` ignores. Audit
source, not artifacts.

For a whole-repo sweep, fan out sub-agents by codebase size:

- **Small** (≲100 source files): run the lens passes yourself, sequentially.
- **Medium** (≲1,000): one sub-agent per occurrence lens, each sweeping the
  whole target in parallel.
- **Large**: partition by top-level module or directory, one sub-agent per
  partition running all lens passes; merge candidate lists before verifying.

Each sub-agent gets the target list, this workflow's sweep instructions, and
the index section(s) for the lens or lenses it will sweep, nothing more. In Claude
Code with this plugin installed, dispatch `subagent_type=leek-skills:smell-sweeper`
(read-only, no project CLAUDE.md, a cheaper model); elsewhere, any read-only
sub-agent, on the cheapest model the harness lets you pick: the sweep is recall
only, and verification runs here on the main model.

### 2. Sweep: one detection pass per occurrence lens

Read [references/index.md](references/index.md) first. It groups all 56 smells
under the 9 occurrence lenses with a one-line description each, **the index
is the only source of lens membership; never sweep from a remembered smell
list**.

Run one detection pass per lens. Each pass is armed only with that lens's
one-line descriptions and scans the target for code matching any of them.
When code plausibly matches, record a candidate:

```text
candidate: <smell slug> · <file:line-range> · <one-line evidence>
```

Do not read full cards during the sweep: cards are loaded per candidate in
the verify step (progressive disclosure). Do not judge, rank, or filter yet;
the sweep errs toward recall, the verify step supplies precision.

### 3. Verify: adversarially, against the card

Every candidate must survive re-examination before it may enter the report.
For each one:

1. Read the full card at `references/smells/<slug>.md`.
2. Re-read the candidate code as a skeptic: does it actually meet the card's
   definition paragraph and detection heuristics, or is it a near-miss that
   merely trips a surface signal (length, a keyword, a shape)?
3. **Cite the definition**: a surviving finding must quote or closely
   paraphrase the specific sentence of the card's definition the code
   satisfies; that citation becomes the finding's qualification rationale.
   If no sentence of the definition fits, the candidate fails.
   For a smell that turns on references (Dead Code, Lazy Element, Middle Man,
   Feature Envy, Shotgun Surgery, Speculative Generality), count the call sites
   rather than eyeball them: with a language server (in Claude Code, the `LSP`
   tool's `findReferences` / `incomingCalls`), otherwise `rg` for the symbol,
   and say in the rationale that the count is approximate.
4. Drop candidates that fail the definition, **even if the code is ugly**, 
   taste is not a criterion, the card is. Dropped candidates never appear in
   the report; keep only a count of them for the report header.

While the card is open, capture what the report needs from it: the obstruction
tag (the middle term of the card's taxonomy line) and the card's suggested
refactorings.

### 4. Report: ranked, durable

Write the findings to a markdown file so audits can be compared over time:
`docs/audits/code-smells-<scope>-<YYYY-MM-DD>.md` in the audited repo
(create the directory if needed), unless the user names another path.

Order findings by **judged severity/leverage**: blast radius, how squarely
the definition is met, how likely the code is to be touched again. Judge each
finding on its own; **never use the taxonomy as a severity proxy**: lens and
obstruction are tags for sweeping and reading, not ranks. State the ranking
rationale in one line per finding.

Every finding carries all of:

- **Smell**: the card's title
- **Location**: `file:line-range`
- **Why it qualifies**: the rationale from the verify step, citing the
  card's definition
- **Obstruction**: the card's obstruction tag
- **Suggested refactorings**: from the card

Report skeleton:

```markdown
# Code Smells Audit: <scope>, <date>

Target: <resolved target> · Lenses swept: <n> · Candidates: <n> · Dropped in
verify: <n> · Findings: <n>

## 1. <Smell Name>: `path/to/file.php:12-84`

- **Severity/leverage**: <rank rationale, one line>

From leek/agent-skills, MIT.

More from leek/agent-skills