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):

   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).

     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):

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

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

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

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

     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):

     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>