synesenom/ran / .claude/skills/fix-smells
fix-smells
VerifiedFix Smells Skill
You are eliminating all code smells in a target file using CodeScene's Code Health analysis as your guide.
Core Principle
Use CodeScene's MCP tools to diagnose, fix, and verify code health in the target file. Fix smells one at a time, verify the score improves after each, and keep only fixes that either improve the score or leave it unchanged while genuinely cleaning up the code. Never change observable behavior — only internal structure, naming, and organisation.
The default scope is the single target file. But some smells cannot be fixed correctly within one file — a "God File" doing too many unrelated things needs to be split into smaller files; logic duplicated across files needs to be merged into one shared implementation; extracting a helper may only make sense in a new sibling file. When the smell genuinely requires it, you are allowed to create new files, split the target file into smaller ones, merge it with another file, or edit other files (e.g. import sites, namespace index.js re-exports). This is a last resort driven by what CodeScene's review actually recommends — not a general license to refactor unrelated files. Keep the blast radius as small as the smell demands and no smaller.
When to Use
Use this skill when:
- A file has a Code Health score below 10.0
- You want to systematically eliminate all code smells in a specific file
- The CLAUDE.md "Code Health" rule triggers (score below 10.0 after an edit)
Workflow
When the user invokes /fix-smells <file>:
1. Resolve the File
- If the argument is a relative path, resolve it against the repo root (
/home/user/ran/<arg>) - If no argument is provided, report usage and stop: "
/fix-smells <file>— pass the path to the file to clean"
2. Baseline Measurement
Call mcp__codescene__code_health_score on the file and record the score.
If the score is 10.0, report:
"File is already at optimal Code Health (10.0). Nothing to fix."
…and stop.
3. Get Detailed Review
Call mcp__codescene__code_health_review on the file. Parse the returned output to produce a numbered list of smells, ordered by impact (highest-penalty smells first). For each smell note:
- Category (e.g. "Complex Method", "Deep, Nested Complexity", "Bumpy Road Ahead", "Large Method", "God Class"/"God File", "Duplicated Code", etc.)
- Location (function/method name and line range if given)
- CodeScene's guidance for fixing it
- Whether the guidance implies a multi-file fix (splitting the file, merging with another, or touching call sites) — flag these explicitly so the plan step can scope them correctly
Report the smell list as a progress checklist:
Baseline: — smell(s) identified
- 1.
<category>—<location>()- 2. …
4. Fix Smells (Iterative Loop)
Work through the smell list top-to-bottom. For each smell:
a. Read the affected code
Use Read on the relevant section of the file (include enough surrounding context to understand the full function/block).
b. Plan the minimal fix Apply CodeScene's guidance. Typical fixes by category:
- Complex Method / Deep, Nested Complexity: extract inner logic into helper functions with clear names; flatten guard clauses with early returns
- Bumpy Road Ahead: invert conditions and return early to eliminate nesting levels
- Large Method: extract cohesive sub-steps into named helpers
- Primitive Obsession: introduce a descriptive variable or constant for repeated magic literals
- Missing Error Handling: add the minimal guard or throw specified by the project's error conventions
- Duplicated Code (within file): extract shared logic into a single named helper and call it from both sites
- Duplicated Code (across files): extract the shared logic into one file (a new helper file, or one of the existing duplicate sites promoted to canonical) and have every other site import it — see "Multi-file fixes" below
- God Class / God File (too many responsibilities): split the file into cohesive smaller files along its natural seams (e.g. one file per responsibility/section) — see "Multi-file fixes" below
Only fix the targeted smell. Do not clean surrounding code speculatively. Prefer a single-file fix whenever one exists; reach for a multi-file fix only when CodeScene's guidance (or the smell itself, e.g. a file mixing unrelated concerns) genuinely requires it.
c. Apply the fix
Use the Edit tool for single-file changes. For a fix that requires splitting, merging, or creating files, follow "Multi-file fixes" below before proceeding. Keep diffs minimal — extract only what the smell demands.
d. Lint check
npm run standard
Run across the whole repo (the default), which also catches stale imports in files you didn't directly edit. If linting fails, revert the fix (Edit, or git checkout -- / delete for newly created files) and mark the smell as SKIPPED (lint fail).
e. Score check
Call mcp__codescene__code_health_score again — on the original target file, and on every file the fix touched or created. If any touched file's score regressed relative to its own baseline (or a newly created file scores below 10.0 for a trivial extraction), revert the whole fix and mark the smell as SKIPPED (score regressed).
f. Update the checklist — mark the smell [x] (fixed) or [ ] SKIPPED.
Multi-file fixes
When a smell requires touching more than the target file:
- Splitting a file: create new file(s) following the project's naming conventions (kebab-case filenames,
_prefix for module-private files per CLAUDE.md). Move the relevant code verbatim where possible. If the original file is re-exported by a namespaceindex.js(e.g.src/dist/index.js), update it so the public import paths and named exports are unchanged unless the user explicitly asked for an API change. Grep the repo for every other file importing the original path and update those imports. - Merging files: fold the duplicate/obsolete file's content into the canonical file, delete the obsolete file, and grep the repo for every import of the deleted file's path — redirect each to the merged location.
- Touching call sites: if a helper's signature or location changes, update every caller found via
Grep, not just the ones in the target file. - Never change the observable public API (exported names, function signatures, return values) as a side effect of a multi-file fix — a smell fix is internal restructuring, not a breaking change. If the smell cannot be fixed without an API change, skip it and note that in the report instead of making the change silently.
5. Full Test Suite
After all smells are processed, run:
npm run standard
npm test
If tests fail: use git status / git diff to identify all applied fixes (including any created, split, merged, or deleted files), then bisect manually — revert the most recent fix (and any files it introduced) and re-run npm test until the suite is green. Mark reverted fixes as SKIPPED (test regression).
6. Test-File Verification (only when the target — or a created/split/merged file — is itself under test/)
npm test passing is not sufficient evidence that a refactor of shared test infrastructure preserved behavior: the suite can stay green while an assertion has quietly become powerless (a dropped assert, a continue→return conversion that returns before the check runs, a comparison degenerated into a tautology). See "Verifying refactors of shared test infrastructure" in CLAUDE.md's Testing Conventions for the full rationale. Run both of the following before step 7, for every independent code path the fixes touched (e.g. a discrete branch and a continuous branch of the same helper count as two paths):
- Golden-master diff:
git show <parent-commit>:<path>the pre-refactor version of the file into a throwaway location, run the same exported entry points from both versions against a few representative real inputs (chosen to hit each branch touched), wrap their collaborators in a spy that logs every call/argument, and assert the logs are identical between old and new. - Mutation test: temporarily inject a real, plausible bug into the production code the helper is meant to catch, rerun the affected slice of the suite, confirm it fails through the refactored helper specifically, then revert the injected bug and confirm a clean
git diff.
Both harnesses are throwaway — write them in the scratchpad or as a temporary file, and delete/revert before step 7. If either check surfaces a divergence, treat it as a test regression: fix or revert per step 5's bisection process before proceeding.
7. Final Measurement
Call mcp__codescene__code_health_score and mcp__codescene__code_health_review one final time on the original target file and on every file created, split into, or merged as part of the fixes, to confirm the achieved score(s) and any remaining smells.
8. Report
Code Health:
<file>Score: →
Files touched: (+ any created/split/merged files, or "none — single-file only")
Fixed ():
<category>at<location>— <one-line description of what changed, noting any other files involved>Skipped ():
<category>at<location>— <reason: lint fail / score regressed / test regression / would break public API / out of scope>Remaining smells: <0 / list if any>
Tests: All passing
Test-file verification: <"N/A — no test/ files touched" / "golden-master diff + mutation test on code paths, no divergences">
Rules
DO:
- Fix smells in impact order — highest-penalty first
- Default to a single-file fix; only split, merge, or create files when the smell genuinely requires it
- Verify the score with
mcp__codescene__code_health_scoreafter every individual fix, on every file that fix touched or created - Revert any fix that regresses the score (on any touched file) or breaks tests
- When splitting or merging files, update the namespace
index.jsand every importer found viaGrepso the public API surface is unchanged - Follow the project's error and return-value conventions when adding guards
- Follow the project's file naming conventions (kebab-case,
_prefix for module-private files) for any new file - Run
npm run standardafter each fix — catch style regressions immediately, including stale imports in files outside the target - Update
CHANGELOG.mdunder## [Unreleased] → ### Changedwith a one-liner if the final score improved (e.g., "Code Health ofsrc/foo.jsimproved from 7.4 → 9.1"), naming any file split/merge involved - When the target (or a file split/merged as part of the fixes) is under
test/, run the golden-master diff and mutation test from step 6 before reporting completion — a greennpm testalone does not prove a refactored assertion can still fail
DO NOT:
- Change observable behavior — no renamed public APIs, no altered return values, no changed parameter signatures, even when a fix spans multiple files
- Inline tests, docs, or comments as part of the smell fix (those are separate concerns)
- Touch files outside the smell's actual footprint — multi-file changes are allowed only when the smell itself spans files (a God File split, a cross-file duplication merge, updating call sites for a moved helper), never as a general excuse to refactor unrelated files
- Skip the final
npm testrun - Skip the step 6 golden-master/mutation verification when the target is a test file — trust a green
npm testalone - Report a smell as fixed without confirming the score did not regress on every file involved
- Commit or leave behind the throwaway golden-master/mutation-test harness files — they are diagnostic scaffolding, not part of the deliverable
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |