/refactor-simple

name: refactor-simple
description: Read-only code quality analysis of the branch against the remote default branch for small to medium changes - classifies the diff, derives conventions from the target repo, and writes a refactor plan to ./tmp/. Usually run by the refactor orchestrator; use directly for a quick pre-PR check on 2-10 files.

Simple Refactor

**Read-only code quality analysis for small to medium changes.**

Safe to run anytime. Analyzes the branch against the target repository's own conventions and writes a refactor plan without modifying files.

What This Does

Fast, focused code quality analysis that: 1. Classifies your changes (size, type, complexity) 2. Learns the conventions of the repository you are in 3. Identifies code smells and convention violations in the lines you changed 4. Generates a refactor plan with auto-fixable and manual issues 5. Writes the plan to `./tmp/` for review

When to Use

• **Small changes** (2-5 files, 50-200 lines)
• **Medium changes** (5-10 files, 200-500 lines)
• **Bug fixes** and **enhancements**
• Quick pre-PR quality check

For large features (>10 files, >500 lines), use `refactor-deep` instead. Simple and deep are the whole set: simple is the cheap pass with the cleanest signal-to-noise, deep is the one that finds real defects in big diffs. Run both on a large PR when you want coverage; their findings overlap by about half and the rest is complementary.

Process

1. Classify Changes

Diff against the merge-base with the remote default branch, never a bare local `main` - a stale local `main` pulls unrelated commits into the review and every finding in them becomes a false positive.

Resolve the PR/current branch's relevant remote and that remote's default branch before running these commands. If either is ambiguous or unavailable, report the blocked comparison; do not guess a remote or silently review an empty diff. Record the resolved remote, base ref, and merge-base for helpers.

# Resolve the relevant remote from the PR/current branch configuration first.
# Set REFACTOR_REMOTE to that verified name; do not assume origin.
git remote show "$REFACTOR_REMOTE"
# Resolve its actual default branch and set BASE to the verified remote ref.
# Fetch that branch explicitly if the ref is missing/stale, then verify it.
git rev-parse --verify "$BASE^{commit}"
MB=$(git merge-base "$BASE" HEAD)
git diff "$MB" --name-status
git diff "$MB" --numstat
git diff "$MB" --stat

Also enumerate non-ignored untracked files with `git ls-files --others --exclude-standard -z`. Treat these as added files: include their full contents and handwritten line counts in sizing and analysis, applying the same generated/vendor/lockfile exclusions. Pass this file inventory to every analyzer; plain `git diff` omits it. Do not stage files to inspect them.

`$BASE` is the remote's real default branch (`main`, `master`, `develop`), never an assumed name. Diffing from the merge-base to the working tree - one revision, not two - includes committed, staged, and unstaged work, so a pre-PR run sees the edits that are not committed yet.

If the branch is behind `$BASE`, note it once as "rebase before merge"; it is not a finding and does not lower the score.

**Determine:**

• **Size**: Tiny (<50) | Small (50-200) | Medium (200-500)
• **Type**: Bug Fix | Enhancement | Refactor
• **Complexity**: Trivial | Simple | Moderate
• **Layers**: Backend | Frontend | Both

Size counts changed source lines. A lockfile, generated file, or vendored directory can add thousands of lines and no complexity - say so and classify on the hand-written change.

2. Learn the Repository's Conventions

Conventions come from the repository you are in, never from a rule remembered from another repo. In order:

1. Read `CLAUDE.md` / `AGENTS.md` at the root and in every directory the diff touches. These state the conventions the maintainers actually enforce. 2. Read two or three exemplar files that neighbour the changed code - files the maintainers clearly consider done - and note how they import, structure, handle errors, and document. 3. Before flagging any convention violation, confirm the convention exists here. `grep` how many existing files already do the thing. If the codebase does it everywhere, it is the convention, not a violation.

An import style is a finding only when the target repository's guidance and existing code establish that convention. Explain the actual impact rather than assigning severity from a preference remembered from another project.

**Pattern Matrix:**

• **Tiny/Bug Fix** → Universal smells only
• **Small/Enhancement** → Universal + the repo's basic architecture rules
• **Medium** → Universal + architecture + documentation for new files

**Universal Smells (any repository):**

• Long functions (>100 lines), deep nesting (>3 levels)
• Magic numbers/strings
• Missing or swallowed error handling on new paths
• Unused imports/variables, commented-out code, TODOs without context
• Duplicate logic: two similar functions, hooks, or types where one with

options would do

• New public surface without a file-level or symbol-level comment when the

neighbouring code has them

**Repo-Derived Rules (Small+):** import style, layering (where logic is allowed to live), state-management and hook patterns, error types, test conventions - whatever steps 1-3 above surfaced, cited to the file that states them.

3. Analyze Files

Read the changed files and the non-ignored untracked file inventory gathered above:

git diff "$MB" --name-only

**Pre-existing vs introduced:** only issues in lines this branch adds or changes count against the PR. Pre-existing debt in touched files may be listed under Info as "pre-existing, not against this PR" and never lowers the score. Read enough surrounding code to tell the difference - a `git blame` on the line settles it.

4. Generate Report

Write the plan to `./tmp/simple-refactor-plan-[timestamp]