---
name: factorize
description: Scan the project for duplication and factorization opportunities
argument-hint: [path/to/dir | --dry-run | --scope <small|medium|large>]
---

Scan the codebase to detect duplicated code, repeated patterns, and factorization opportunities. Unlike `/simplify` (which refines recently changed code), this command performs a **project-wide** analysis.

**Modes:**
- `/factorize` — full scan, all source files
- `/factorize src/services` — scoped to a specific directory
- `/factorize --dry-run` — report only, no code changes
- `/factorize --scope small` — override auto-detected project size

## Step 1 — Context

1. Read `CLAUDE.md` to understand:
   - Stack (language, framework, conventions)
   - Project structure (where source lives, what's generated/vendored)
   - Naming conventions and existing abstractions

2. Detect project size:
   - Count source files (exclude tests, config, generated, vendor, node_modules)
   - **Small** (< 30 files): 1 analysis agent
   - **Medium** (30-100 files): 2 agents (split by directory)
   - **Large** (> 100 files): 3 agents (split by layer/concern)

3. Present the plan:
   ```
   FACTORIZE — [project name]
   Stack: [detected]
   Scope: [full / directory]
   Size: [X source files] → [small/medium/large]
   Agents: [1-3]
   Mode: [analysis + refactor / dry-run (report only)]

   Proceed? [Y/n]
   ```

## Step 2 — Detection phase

Launch agents in parallel (subagent_type: `feature-dev:code-explorer`).

Each agent receives its assigned files and this mission:

```
You are analyzing [project name] ([stack]) for factorization opportunities.
Your assigned files: [list].

Scan for these patterns:

1. **DUPLICATED CODE** — identical or near-identical blocks (>5 lines) that appear in 2+ files.
   Report: both locations, the duplicated block, and a suggested shared function/module name.

2. **REPEATED PATTERNS** — same logical pattern implemented differently across files
   (e.g., 3 different ways to validate input, 4 similar API call wrappers).
   Report: all occurrences, the common pattern, and a suggested unified approach.

3. **MISSED ABSTRACTIONS** — operations that could benefit from a shared utility
   (e.g., repeated string transformations, common data reshaping, recurring error handling).
   Report: occurrences and suggested abstraction.

4. **COPY-PASTE DRIFT** — code that was clearly copied then modified slightly,
   creating divergence that will cause bugs (one copy gets fixed, others don't).
   Report: all copies, the differences, and which version is likely "correct".

For each finding, report:
- **Type**: DUPLICATION / PATTERN / ABSTRACTION / DRIFT
- **Impact**: HIGH (>3 occurrences or >20 lines each) / MEDIUM (2-3 occurrences) / LOW (minor)
- **Locations**: file:line for each occurrence
- **Code snippets**: the duplicated/similar blocks (abbreviated if >15 lines)
- **Suggestion**: concrete refactoring approach (function name, module location, signature)

Do NOT report:
- Similar test setup code (tests are allowed to be repetitive for readability)
- Framework boilerplate that cannot be abstracted (e.g., route definitions)
- Config files or generated code
- Differences that are intentional (check comments, commit messages)
```

## Step 3 — Consolidation

After agents return, act as the senior architect:

1. **Merge overlapping findings** — if two agents found the same duplication from different files, merge into one finding.

2. **Rank by ROI** — for each finding, estimate:
   - **Effort**: how many files need to change, is it a simple extract-function or a design change?
   - **Benefit**: how much duplication is eliminated, what's the maintenance risk if left as-is?
   - **Risk**: could this refactoring break things? Is it well-covered by tests?

3. **Filter out low-ROI noise** — if the effort exceeds the benefit (e.g., extracting a 3-line helper used twice), drop it with a 1-line justification.

4. **Group into refactoring units** — things that should be done together because they touch the same files or create the same abstraction.

## Step 4 — Report (always)

Generate and save to `factorize-reports/YYYY-MM-DD_HH-MM.md`:

```markdown
# Factorize Report — [project name]
**Date:** [timestamp]
**Stack:** [detected]
**Scope:** [full / directory path]
**Files analyzed:** [count]
**Agents used:** [count]

## Summary

| Type | HIGH | MEDIUM | LOW | Total |
|------|------|--------|-----|-------|
| Duplication | X | X | X | X |
| Repeated pattern | X | X | X | X |
| Missed abstraction | X | X | X | X |
| Copy-paste drift | X | X | X | X |

**Estimated impact:** ~[X] lines of code can be eliminated or consolidated.

## HIGH impact findings

### [F-1] [Type] — [short title]
- **Impact:** HIGH
- **Locations:**
  - `file1.ext:L10-L25`
  - `file2.ext:L42-L57`
  - `file3.ext:L8-L23`
- **Duplicated block:**
  ```[lang]
  [code snippet]
  ```
- **Suggestion:** Extract to `[module/function name]` in `[suggested path]`
- **Effort:** [XS/S/M] — [brief justification]
- **Risk:** [low/medium — test coverage status]

## MEDIUM impact findings

| # | Type | Title | Locations | Suggestion | Effort |
|---|------|-------|-----------|------------|--------|
| 1 | ... | ... | file1, file2 | ... | S |

## LOW impact findings (informational)

[Brief list — no action expected unless convenient]

## Rejected findings

| # | Finding | Reason |
|---|---------|--------|
| 1 | ... | Intentional difference / framework constraint / ROI too low |

## Recommended refactoring plan

### Wave 1 — Quick wins (XS-S effort, high impact)
1. [F-X] Extract `[function]` from [files] → [target module]
2. [F-Y] Unify [pattern] across [files]

### Wave 2 — Medium effort
3. [F-Z] Create shared [abstraction] for [concern]

### Wave 3 — Large refactoring (discuss first)
4. [F-W] Restructure [area] — requires design decision
```

Create `factorize-reports/` if it doesn't exist.
Add `factorize-reports/` to `.gitignore` if not already present.

## Step 5 — Apply (unless --dry-run)

If NOT in dry-run mode, ask:

```
[X] findings ready to apply.
Recommended approach:
  Wave 1: [X] quick wins ([list of F-IDs])
  Wave 2: [X] medium refactors
  Wave 3: [X] need discussion first

Apply Wave 1 now? [Y/n/all]
```

- **Y** → apply Wave 1 only, then ask for Wave 2
- **all** → apply Waves 1 + 2 (never auto-apply Wave 3)
- **n** → stop, report is saved

For each applied refactoring:
1. Create the shared function/module
2. Replace all occurrences with calls to the shared version
3. Run the project's test command (from CLAUDE.md) after each wave
4. If tests fail → revert the wave, report which refactoring caused the failure

## Step 6 — Tickets

For findings NOT applied (Wave 3, or if user chose dry-run):
- If `BACKLOG/` exists → create IMP tickets (scan IDs, anti-conflict)
- Use the standard ticket format with the factorize finding details
- Reference the report: `See factorize-reports/[filename].md, finding F-X`

## Rules — NON-NEGOTIABLE

- **Read CLAUDE.md first** — respect project conventions for where shared code lives
- **Wait for user confirmation** after the plan (Step 1) AND before applying (Step 5)
- **Never auto-apply Wave 3** — large refactorings need human decision
- **Run tests after each wave** — revert if broken
- **Never refactor test code** — tests can be repetitive, that's fine
- **Never create FEAT tickets** — factorization is improvement, not new features
- **Reports contain code snippets** — gitignore them
- **Dry-run is the safe default** — if user seems unsure, suggest --dry-run first