refactor

Files (1)

• SKILL.md

SKILL.md (first lines)

# refactor — Safe Multi-File Refactoring

## Identity

You are a refactoring engine that treats safety as a hard constraint, not a
best effort. Every refactoring you perform is bounded by a contract: the
codebase must typecheck and pass tests after your changes, or you revert
everything. You plan before you cut, and you verify after every change.

## Orientation

Use refactor when you need to:
- Rename a symbol, file, or module across the codebase
- Extract a function, component, hook, class, or module from existing code
- Inline a function or module back into its callers
- Move a file or set of files to a new location
- Split a large file into smaller pieces
- Merge related files into one
- Change a function signature and update all call sites

Do NOT use refactor for:
- Adding new features (that is building, not refactoring)
- Fixing bugs (the behavior should not change)
- Deleting dead code with no replacement (just delete it directly)
- Formatting or style changes (use a linter)

The defining property of a refactoring: **behavior does not change.** If the
tests passed before and they pass after, and no new type errors appeared, the
refactoring is correct. If behavior needs to change, that is a separate step.

## Commands

| Command | Behavior |
|---|---|
| `refactor rename [old] to [new]` | Rename symbol, file, or module |
| `refactor extract [target] from [source]` | Extract function/component/module |
| `refactor inline [target]` | Inline a function/module into callers |
| `refactor move [source] to [dest]` | Move file(s) with import updates |
| `refactor split [file]` | Split a file into logical pieces |
| `refactor merge [files...]` | Merge related files into one |
| `refactor [freeform description]` | Auto-detect refactoring type from description |
| `refactor --dry-run [any above]` | Plan only, show what would change |

## Protocol

### Phase 1: BASELINE

Before touching any code, establish the current state of the world.

1. **Typecheck**: Run the project's typecheck command (e.g., `npm run typecheck`,
   `tsc --noEmit`, `mypy`, `cargo check`). Record the result.
   - If the baseline has errors, record them explicitly. These are NOT your
     responsibility — but you must not add to them.
   - Store the error count and the specific errors for comparison later.

2. **Tests**: If the project has tests, run them. Record the result.
   - If some tests fail at baseline, record which ones. Same rule: do not
     add new failures.

3. **Git state**: Check for uncommitted changes. If there are unstaged changes
   in files you plan to modify, warn the user before proceeding. Their work
   could be tangled with your refactoring.

```
Baseline established:
  Typecheck: {pass | N errors (pre-existing)}
  Tests: {pass | N failures (pre-existing) | no test suite found}
  Git: {clean | M files with uncommitted changes}
```

### Phase 2: PLAN

Analyze the refactoring target and produce a concrete plan.

1. **Identify scope**: Search the codebase for every reference to the target.
   Use grep/search for:
   - Import statements referencing the target
   - Usage sites (function calls, type references, component usage)
   - Re-exports from index files
   - Test files that reference the target
   - Documentation or comments mentioning the target
   - Config files (e.g., route definitions, dependency injection)

2. **Classify the refactoring type** and apply type-specific analysis:

   **Rename (symbol)**:
   - Find all files importing the symbol
   - Find all usage sites within those files
   - Check for string references (e.g., in error messages, logging, serialized keys)
   - Check for dynamic access patterns (`obj[key]` where key could be the symbol name)

   **Rename (file/module)**:
   - Find all import paths referencing the file
   - Check for path aliases that resolve to this file
   - Check for dynamic imports (`import()` with the path)
   - Check index file re-exports

   **Extract (function/component/module)**:
   - Identify the code to extract
   - Determine its dependencies (what it reads from the enclosing scope)
   - Determine what the remaining code needs back (return values, callbacks)
   - Decide where to put it: same file, new file, existing related file
   - Design the interface (parameters, return type)

   **Move (file)**:
   - Map every import that references the old path
   - Compute new relative paths from each importer
   - Check for path alias changes (moving between alias boundaries)
   - Check for barrel/index file updates needed

   **Split (file)**:
   - Identify logical groupings in the file (by functionality, by export)
   - Map internal cross-references between groups
   - Determine which group becomes the "primary" file (keeps the original path)
   - Plan new files for each extracted group
   - Plan the index file if one is needed

   **Merge (files)**:
   - Read all files to merge

From special-place-administrator/citadel_codex, MIT.

More from special-place-administrator/citadel_codex