/refactor-deep

name: refactor-deep
description: Read-only comprehensive analysis of the branch against the remote default branch for large features - derives conventions per layer, hunts for correctness defects in the new code paths, and writes a prioritized refactor plan to ./tmp/. Usually run by the refactor orchestrator alongside refactor-simple; use directly on 10+ file changes.

Deep Refactor

**Comprehensive read-only analysis for large features and architectural changes.**

Safe to run anytime. Performs deep analysis against the target repository's own conventions, hunts for correctness defects in the new code paths, and writes a detailed refactor plan without modifying files.

What This Does

Thorough code quality analysis that: 1. Classifies changes with detailed metrics 2. Learns the conventions of the repository you are in, per layer 3. Analyzes each layer the diff touches against those conventions 4. Hunts for correctness defects in the new code paths (the part that finds real bugs - unguarded I/O, bypassed guards, lifecycle and cleanup gaps) 5. Checks cross-cutting concerns (SOLID, DRY, documentation, error handling) 6. Writes a comprehensive, prioritized plan to `./tmp/`

When to Use

• **Large features** (10-20 files, 500-1000 lines)
• **Huge features** (20+ files, >1000 lines)
• **Architectural changes** requiring comprehensive validation
• **Pre-PR comprehensive check** for complex work

For small/medium changes, use `refactor-simple` instead. Simple and deep are the whole set; on a large PR their findings overlap by about half and the rest is complementary, so running both is coverage, not redundancy. Do not run this command three times and merge the results - repeated runs on the same diff converge on the same findings, and a merge step has been shown to lose the severe ones.

Process

Phase 0: Classification & Convention Discovery

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.

**Classify:**

• **Size**: Large (500-1000 lines) | Huge (>1000 lines) - of hand-written

change. Lockfiles, generated files, and vendored directories are excluded from the count and named as excluded.

• **Type**: New Feature | Major Refactor | Enhancement
• **Complexity**: Complex | Very Complex - judged on the change, not the line

count. A huge diff that is one mechanical operation is not Complex; say so.

• **Layers**: list them as this repository names them (for example

main/preload/renderer in an Electron app; api/webapp in a monorepo)

• **Modules**: affected modules

**Discover conventions, per layer.** Conventions come from the repository you are in, never from a rule remembered from another repo:

1. Read `CLAUDE.md` / `AGENTS.md` at the root and in every directory the diff touches. 2. For each layer, read two or three exemplar files that neighbour the changed code and note how they import, structure, handle errors, test, 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.

**Show classification to user:**

📊 Change Classification:
Size:       Large (15 files, 742 hand-written lines; lockfile excluded)
Type:       New Feature (12 added, 3 modified)
Complexity: Complex (multiple modules)
Layers:     [as the repo names them, with file counts]
Modules:    [list]
Diff base:  merge-base with $BASE at [sha], to working tree

📋 Conventions sourced from:
[the guidance files and exemplars read in step 1-2]

Proceeding with comprehensive analysis...

Phase 1: Per-Layer Convention Analysis

For each layer the diff touches, check the changed code against the conventions discovered in Phase 0, citing the file that states each one. Typical dimensions - fill them from the repository, do not assume:

• **Import style**: alias vs relative, ordering, allowed cross-layer imports
• **Layering**: where logic is allowed to live (handlers vs services, pages

vs hooks, main vs renderer)