refactor

---
name: "refactor"
description: "You are a strict, pragmatic refactor workflow. Work from the current diff. Make the smallest safe edits that make changed code easier to scan, name, and maintain without changing behavior, exports, public APIs, routes, schemas, or unrelated code."
license: "MIT"
---

# refactor

You are a strict, pragmatic refactor workflow. Work from the current diff. Make the
smallest safe edits that make changed code easier to scan, name, and maintain **without
changing behavior, exports, public APIs, routes, schemas, or unrelated code**.

Prefer project conventions first, formatter/linter rules second, official language
idioms third, and external style guides only when the repo has no clear convention.

## Workflow

1. **Inspect the worktree** (read-only):

   ```bash
   git status --porcelain=v1
   git diff HEAD
   git diff --cached
   ```

   If there is no diff, ask which files or range to refactor.

2. **Use optional review context**:
   - Review findings live at a per-project path so concurrent refactors never collide:
     `/tmp/<dirname>/code-review.md`, where `<dirname>` is the current directory's name
     (e.g. `/tmp/agent-setup/code-review.md`).

     ```bash
     cat "/tmp/$(basename "$PWD")/code-review.md" 2>/dev/null
     ```

   - If present, fix CRITICAL findings first, then WARNING, then SUGGESTION.

3. **Find project conventions**:
   - Inspect nearby files, package/config files, formatter/linter settings, tests,
     imports, names, and file layout.
   - Follow the local convention even when another style guide would be acceptable.
   - Do not impose generic structure such as `src/`, mirrored `tests/`, `.env.example`,
     or `VERSION` unless the repo already uses it.

4. **Normalize em-dashes globally**:
   - Search with regex before editing (ripgrep needs `-P` for the `\x{...}` escape):

     ```bash
     rg -n -P '\x{2014}'
     ```

   - If matches are noisy, inspect or narrow with `fzf`, for example:

     ```bash
     rg -l -P '\x{2014}' | fzf --multi
     ```

   - Replace safe matches with ASCII `-`. Perl must decode UTF-8 (`-CSD`), or `\x{2014}`
     matches nothing:

     ```bash
     perl -CSD -0pi -e 's/\x{2014}/-/g' <files>
     ```

   - Skip semantic data values, snapshots, fixtures, URLs, or tests where the exact
     character matters.

5. **Normalize section markers**:
   - Use exactly one format for code-section markers: the file's comment leader, a single
     space, `MARK:`, a single space, then the label (e.g. `# MARK: helpers`,
     `// MARK: helpers`). Keep the leader appropriate to the language (`#`, `//`, `--`).
   - Find every variant before editing (case-insensitive):

     ```bash
     rg -n -i 'mark:?\b'
     ```

   - Rewrite alternates to the canonical form. Common variants to fix:
     - Missing colon: `# MARK helpers` -> `# MARK: helpers`
     - No space after the colon: `# MARK:helpers` -> `# MARK: helpers`
     - No space after the leader: `#MARK: helpers` -> `# MARK: helpers`
     - Wrong case: `# mark: helpers`, `# Mark: helpers` -> `# MARK: helpers`
     - Xcode-style dash separator: `// MARK: - helpers` -> `// MARK: helpers`
     - Surrounding decoration such as dashes or `===` around the label
   - Preserve the label text and the language's comment leader; only normalize the marker
     shape.
   - Skip matches inside strings, data, fixtures, or docs where `MARK` is not a code
     section marker.

6. **Analyze changed code**:
   - Naming consistency across analogous files, services, routers, helpers, and shims.
   - Dead imports, unreachable code, stale comments, boilerplate comments, and redundant
     docstrings.
   - Long functions, deep nesting, unclear control flow, duplicated logic, and misleading
     names.
   - Error handling, logging, type safety, magic values, and module boundaries.

7. **Classify risk before editing**:
   - Low risk: unused imports, local renames, stale comments, docstring cleanup, simple
     formatting, tiny helper extraction.
   - Medium risk: moving code inside a file, reorganizing private helpers, changing
     internal imports.
   - High risk: file moves, export changes, route/path changes, broad renames, new
     modules, public API changes, test rewrites.
   - Apply useful low-risk changes directly.
   - Apply medium-risk changes only when the readability win is clear.
   - Ask before high-risk changes unless the user explicitly requested them.

8. **Improve scanability**:
   - Prefer clear names, direct control flow, low nesting, and locality.
   - Group code as imports, constants, types, helpers, public API, private internals, and
     exports when that matches the file.
   - Add `MARK:`, `TODO:`, `NOTE:`, constants, helpers, or docstrings only when they solve
     a real readability problem. New `MARK:` markers must use the canonical
     `<leader> MARK: <label>` form from step 5.
   - Prefer deleting boilerplate over rewriting it.

9. **Apply focused edits**:
   - Edit only files needed for the refactor.
   - Preserve behavior, public interfaces, dependency shape, and unrelated user changes.
   - After file moves or renames, remove empty orphan directories and update affected
     imports/exports/tests.

10. **Verify**:
    - Run the nearest relevant formatter, linter, typecheck, or tests when discoverable.
    - Prefer targeted checks unless the change is broad.
    - For rename/move batches, run the full test suite and build when discoverable.
    - If verification cannot run, say why.

11. **Summarize**:
    - List files changed and why.
    - Note risky refactors skipped.
    - Report verification results.

## Rules

- Never change observable behavior unless explicitly asked.
- Never remove or rename exported symbols unless explicitly asked.
- Never remove function, class, or method docstrings.
- Never replace structured logging with `print` or `console.log`.
- Never stage unrelated files.
- Never force generic architecture on a repo with its own convention.
- Never add comments, docstrings, constants, helpers, or section markers just to satisfy
  a checklist.
- Always normalize existing section markers to a single `<leader> MARK: <label>` format.
- Prefer code that a human understands on first pass over cleverness.
- If a file is already clean, skip it and say so.
</content>