refactor

What this skill does

<tool_restrictions>

# MANDATORY Tool Restrictions

## BANNED TOOLS — calling these is a skill violation:

- **`EnterPlanMode`** — BANNED. Do NOT call this tool. This skill has its own structured process.
- **`ExitPlanMode`** — BANNED. You are never in plan mode.
  </tool_restrictions>

<arc_runtime>
This workflow requires the full Arc bundle, not a prompts-only install.

Paths in this skill use these conventions:

- `agents/...`, `references/...`, `disciplines/...`, `templates/...`, `scripts/...`, `rules/...`, `skills/<name>/...` are Arc-owned files at the plugin root. Resolve the plugin root from this skill's filesystem location — it's the directory containing `agents/` and `skills/`.
- `./...` is local to this skill's directory.
- `.ruler/...`, `docs/...`, `src/...`, or any project-relative path refers to the user's project repository.
  </arc_runtime>

<required_reading>
Before starting, read these references:

1. `references/architecture-patterns.md` — import depth rules, boundary violations
2. `references/component-design.md` — compound vs simple component patterns
3. `references/maintainability-review.md` — strict god-file, duplication, and structural simplification bar
4. `references/complexity-optimization.md` — safe optimization patterns and behavior-preservation checks

Also read, when present in the target project:

- `CONTEXT.md` or the relevant context from `CONTEXT-MAP.md`
- `docs/adr/*.md` or area-specific ADRs
  </required_reading>

# Architectural Refactoring

Discover structural friction, propose deep-module refactors, and create project-local RFCs.

<boundary>
This workflow reviews existing code with the explicit goal of creating a refactoring plan or RFC.

- If the primary issue is reusable UI component cataloguing, missed shared UI package usage, or design-system component extraction, recommend the dedicated componentization workflow instead.
- If the primary issue is an overgrown component, script, module, or duplicated implementation logic, keep it in `/arc:refactor`.
- If the primary issue is broad codebase health, security, performance, or test coverage, recommend `/arc:audit`.
- If the user wants implementation, stop at a clear plan unless they explicitly ask to start implementing.
- Do not create external tracker issues unless the user explicitly asks.
  </boundary>

## Architecture Language

Use these terms consistently:

- **Module** — anything with an interface and an implementation: a function, class, package, app slice, or tier-spanning feature.
- **Interface** — everything a caller must know to use the module correctly: types, invariants, ordering, error modes, config, and performance characteristics.
- **Implementation** — the code inside a module.
- **Depth** — leverage at the interface. A deep module gives callers a lot of behavior through a small interface; a shallow module exposes nearly as much complexity as it hides.
- **Seam** — where an interface lives; a place behavior can be altered without editing in place.
- **Adapter** — a concrete thing satisfying an interface at a seam.
- **Leverage** — what callers get from depth.
- **Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrated in one place.

From John Ousterhout's _A Philosophy of Software Design_:

A **deep module** has a small interface hiding a large implementation. Deep modules are:

- More testable (test at the boundary, not inside)
- More navigable (fewer files to understand a concept)
- More maintainable (changes stay internal)

A **shallow module** has an interface nearly as complex as its implementation. Shallow modules:

- Force callers to understand implementation details
- Create coupling between files that should be independent
- Make testing harder (you test internals, not behaviour)

Apply the **deletion test** to suspected shallow modules: if deleting the module makes complexity vanish, it was pass-through indirection; if deleting it spreads complexity across callers, it was earning its keep.

## Process

### Step 1 — Load domain and decision context

Read the project context before judging architecture:

- If `CONTEXT-MAP.md` exists, use it to find the relevant `CONTEXT.md`.
- Otherwise read root `CONTEXT.md` if present.
- Read ADRs in `docs/adr/` or the relevant area if the candidate touches a documented decision.

Use the project's domain vocabulary when naming candidate modules. If a better module name uses a concept not in `CONTEXT.md`, note that the context should be updated during the grilling loop.

### Step 2 — Scan for decomposition candidates

For JavaScript/TypeScript projects, run the Arc-owned god-file and duplication scanner when available:

```bash
python3 scripts/find-god-files.py . --max-files 40
```

Use `--include-tests` only when the user asks about duplicated tests or test-suite cleanup.

The scanner is heuristic. It ranks likely candidates; it does not decide. Read the highest-ranked files before proposing changes.

Also run the Arc-owned read-only codebase mapper when available:

```bash
python3 scripts/codebase-map.py ${scope:-.} --format markdown
```

Use the map to orient exploration around route surfaces, services, data layer, largest files, high fan-in/fan-out modules, and import cycles. The mapper output is not a finding by itself. Read the relevant files before proposing any refactor.

Classify confirmed candidates:

- `god-component` — React component doing rendering, data shaping, effects, mutations, validation, and subview control in one file.
- `god-script` — CLI/build/migration script mixing argument parsing, I/O, domain logic, formatting, and side effects.
- `god-module` — non-UI module with multiple unrelated responsibilities.
- `duplication` — repeated functions, schemas, UI fragments, query builders, scripts, or formatting logic.
- `shallow-module` — interface nearly as complex as the implementation.
- `package-extraction` — grouped behavior that belongs in a discrete package/module because it has a coherent concept, multiple callers, and a stable interface.

### Step 3 — Explore for architectural friction

Use the Agent tool with `subagent_type=Explore` to navigate the codebase. If the user provided a
path or focus area, start there. Otherwise, explore broadly.

Do NOT follow rigid heuristics. Explore organically and note where you experience friction:

- Where does understanding one concept require bouncing between many small files?
- Where are modules so shallow that the interface is nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
- Where do tightly-coupled modules create integration risk in the seams between them?
- Where is a coherent concern spread across an app and ready to become a discrete package/module?
- Where are god components, god scripts, oversized modules, or mixed responsibilities making changes risky?
- Where is duplication a sign that a shared concept needs one implementation?
- Where do repeated scans, nested lookups, sorting inside loops, rendering churn, or N+1 calls indicate a better data structure or boundary?
- Where are there deep relative imports (5+ levels) indicating boundary violations?
- Which parts of the codebase are untested, or hard to test?
- Where do barrel files re-export everything, hiding the real dependency graph?

The friction you encounter IS the signal.

### Step 4 — Present candidates

Present a numbered list of refactoring opportunities. For each candidate:

| Field                   | Description                                                                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Cluster**             | Which modules/concepts are involved                                                                              |
| **Type**