Refactor Finder

---
name: refactor
description: >
  Scan a codebase or single file for refactor opportunities and emit a
  prioritized plan. Surfaces duplicated logic, oversized functions, deep
  nesting, leaky abstractions, dead code, and dependency smells. Use before
  a feature lands to keep tech debt in check, or during a dedicated cleanup
  sprint to triage dozens of files in one pass.
when-to-use:
  - Planning a refactor sprint
  - Auditing a single module before extending it
  - Hunting for duplication before extracting a shared util
  - Deciding which legacy files to rewrite first
---

# Refactor Finder

Turn the skill loose on a path and it will return a ranked list of
refactors, each with effort, payoff, and a concrete patch sketch.

## Overview

The skill walks the target tree, parses supported languages (TS/JS, Python,
Go, Rust, Java), and scores each file or function against a battery of
heuristics:

- Duplication via token-level shingling across files.
- Cyclomatic complexity and parameter count per function.
- Coupling: incoming/outgoing edges of each module.
- Dead-code: unused exports, unreachable branches, commented-out blocks.
- Naming and consistency drift versus a baseline glossary.

It then ranks opportunities by a `(payoff / effort)` ratio so the user can
attack the top of the list first.

## Usage examples

```bash
# Scan a whole package
npx skills run refactor --path src/

# Limit to one module and only structural smells
npx skills run refactor --path src/billing --categories structure

# Output a markdown plan instead of JSON
npx skills run refactor --path src/ --format md --output refactor-plan.md
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `path` | string | `.` | Directory or file to scan. |
| `categories` | string[] | `all` | Subset of `duplication`, `complexity`, `coupling`, `dead-code`, `naming`. |
| `min_score` | float | `0.5` | Hide opportunities below this score (0–1). |
| `max_results` | int | `30` | Cap returned opportunities. |
| `format` | enum | `json` | `json`, `md`, or `sarif`. |
| `include_tests` | bool | `false` | Whether to scan test files. |

## Expected output

A list of opportunities, each containing:

- `id`, `file`, `range` (line span), `category`, `score`
- `why`: a one-paragraph rationale
- `suggestion`: a code sketch or step-by-step refactor recipe
- `risk`: `low | medium | high`, plus a one-line rollback strategy

Use `--format sarif` to feed the results into a code-scanning dashboard.