Refactor Identification: Branch-Scoped Structural Candidates

Use this skill for a deep, quantified dive on exactly 4 structural categories, when the question is not "does this diff pass review" but "is there a structural refactor worth investing in here". Do not use it as a substitute for a broader code-review checklist pass: that pass already covers part of A1 superficially (its "Abstractions" section and the SRP/OCP portion of "Structural Code Smells") as part of a broad, fast merge gate; reach for this skill only when that surface-level pass isn't enough. See Boundaries below for the exact split. Identify candidates only; never execute a refactor and never explain how to apply a pattern once one is chosen. Route the "how" to pablo-code-philosophy's references/gof/ (pattern catalog) and references/fp/ (FP mechanics); route the cut-off criterion (when NOT to bother) to that same skill.

Scope law: the branch's work only

This skill never scans a whole repository. It only looks at what the current branch changed.

1. Derive the diff (the same first step as any diff-scoped review):
   • If the caller's prompt already hands you a diff (a path, a commit range, or diff content), use exactly that. Do not go looking for a different diff and do not ask anything.
   • Otherwise, derive it yourself: git diff (unstaged), git diff --cached (staged), git diff main...HEAD (full branch). Ask for the parent branch only if invoked standalone and it isn't obvious.
2. Anchoring rule: every finding needs at least one file:line inside a changed hunk, or on a symbol the branch changed. A finding with no such anchor does not exist for this skill.
3. 1-hop context rule: you may read (a) the full contents of every changed file, (b) files that directly define or use a symbol the branch changed (a code-navigation/indexing tool if the repo has one, otherwise grep), and (c) the public signatures (not bodies) of types the changed lines call, solely to detect an existing helper being re-implemented. Do not expand further than one hop.
4. Occurrence-counting exception: once a candidate is anchored inside the branch's diff, a repo-wide grep is allowed solely to count how many total occurrences exist, because the DRY thresholds below (2 for both structural and business duplication) count all occurrences, not just the ones inside the diff. This exception never originates a new candidate; it only measures one already anchored in step 2. A zero-hit grep outside the diff establishes local absence only, never runtime unreachability (see rule 5).
5. Evidence ceiling rule: code/config read within the 1-hop radius, and tests that exercise it, are what settle a candidate. Documentation, wikis, comments, and domain knowledge may only motivate a hypothesis; [NEVER] let them decide a gate row or a finding by themselves. If adjudicating a candidate needs a fact beyond the 1-hop radius or outside this repo (including a fact only documentation claims), do not infer or derive it: name the exact lookup that would resolve it (repo, symbol/path, what to check) and mark the candidate N9/Unresolved. The radius never widens; the verdict is suspended.

The four categories

A1: Missing or misplaced abstractions

A class or function carries more than one reason to change, the same shape of logic is copy-pasted with only the types or literals differing, it inherits for reuse rather than variation, or it mixes separable phases in one body.

2-copy override of DRY: pablo-code-philosophy DRY.md (Three Strikes) waits for 3 copies. In this lens the owner's review rule wins: duplication is a candidate at 2 copies, structural or business, unless the extraction is very expensive (N3 and P3 still apply). DRY.md itself is unchanged.

§ Inheritance-for-reuse is narrower than the deep-inheritance smells code-review-checklist deliberately excludes (Call super, Circle-ellipse, Yo-yo, Poltergeist): those are style-level nitpicks this codebase rarely has; this row only fires when composition would carry the same behavior without an "is-a" claim, operationalizing pablo-code-philosophy's composition-over- inheritance rule (SOLID.md, the L section). Refactor direction: Replace Subclass/Superclass with Delegate, Remove Subclass; never an open subclass hierarchy as the "fix".

A2: Weak encapsulation

State that should be private and self-protecting is instead exposed, mutable, or trusted to be validated by every caller, or a method mixes query with mutation, reads ambient state, or reaches through a delegate chain.

A3: Poor data types

Domain concepts are carried by bare primitives or null, expected outcomes are signaled by throwing instead of by the return type, a field stores a value it could derive instead, or a mutable value is aliased where it should be copied.

A4: Flag/enum-modeled variants

A discriminator drives behavior that varies by case, in a shape that a sealed ADT + pattern matching would express more directly and exhaustively.

When NOT to report (gate)

Every candidate must pass through every row below before it becomes a finding. Check every row against every candidate: at most one row applies (the most specific match, never stacked as rhetorical reinforcement), and a candidate with no matching row passes to Findings. A candidate matching N9 moves to Unresolved or Filtered out as the N9 row says; a candidate matching any other row moves to Filtered out with that row's ID. No candidate is silently dropped; record the row checked in the finding's gate note.

"Filtered out" describes why this lens doesn't surface the item as a structural refactor candidate in this branch. [NEVER] treat it, or cite a row ID, as a claim that the change is wrong, risky, unsafe, or should be rejected.

Rows can be logically incompatible: in particular N8 (rename/formatting/trivial, behavior-preserving by definition) cannot co-apply with any argument that the candidate changes behavior, and N1 (only one variant exists) cannot co-apply with N2 (different business rules exist). Citing incompatible rows together means the candidate is misclassified; stop and re-derive.

† N2 check: compare what each predicate/block accepts (its extension), not the polarity of its call sites. If one's accepted set is a superset/subset of the other's, they are not different rules and N2 does not apply.

‡ N3 check: "harder to read" explicitly includes hiding an effect. If the abstraction that removes the duplication would fold a mutation, a metric, a log, or any other side effect that each duplicated site currently performs in plain sight into a single method's body, N3 applies: a few duplicated, explicit lines beat one abstraction with hidden effects (KISS > DRY). Name this check in the gate note of every A1 structural-duplication candidate whose refactor direction merges call sites that mutate state.

Priority assignment

Assign strictly by this table; no judgment outside it.

Tie-break: if a candidate has multiple evidence lines spanning both a pre-existing root cause and branch-added occurrences, priority follows the root cause, not the occurrence count: P2, not P1. Exception: a copy the branch ADDS next to an untouched one is P1 when the fix stays within files the branch changed (references/examples.md A1); an in-place retype of a pre-existing line stays P2.

Step-by-step process

1. Derive the scope. If the caller's prompt hands you a diff (path, range, or content), use
   exactly that; do not ask. Otherwise: `git diff` (unstaged), `git diff --cached` (staged),
   `git diff main...HEAD` (full branch); ask for the parent branch only if invoked standalone
   and it isn't obvious.
   Verify: you can list every changed file with its hunks.
2. Build the scope table: one row per changed file, with its path, language
   (Java/Scala/JavaScript/TypeScript), and changed line ranges. A file in any other language
   gets language `out of language scope` and yields no candidates.
   Verify: row count == changed-file count.
3. Expand context, 1 hop max: for each changed symbol you may read (a) its full containing
   file, (b) files that directly define or use it (a code-navigation/indexing tool if the repo
   has one, else grep), (c) public signatures (not bodies) of types the changed lines call
   (Scope law 3c). Never expand further.
   Verify: every context file read maps to a named changed symbol.
4. Detection pass A1 over changed hunks + context, using the A1 table and the language cues
   in references/. Record raw candidates: category, smell row, file:line list, measure.
5. Detection pass A2, same procedure.
6. Detection pass A3, same procedure.
7. Detection pass A4, same procedure.
8. Count occurrences for threshold-based candidates: grep repo-wide for the anchored
   pattern; update each candidate's measure. Drop candidates below threshold.
   Verify: every surviving candidate's measure meets its row's threshold.
8b. Merge candidates that share a root-cause line into one RF (one root cause = one fix;
    definition: `pablo-code-review` `references/merge-rules.md` § Root cause); name the
    merged ones in its Evidence line as "also: A<n> <smell row>".
    Verify: no two candidates share a root-cause line.
9. Gate every candidate through N1–N10. Name the one fact that decides the row before picking
   it. If that fact requires evidence outside the 1-hop radius or this repo, stop at N9; never approximate with the closest-looking row. Passing candidates get a one-line gate
   note naming the rows checked; failing candidates move to Filtered out with the failing
   row ID; N9 candidates move to Unresolved or Filtered out as the N9 row says, with the missing fact named.
   Verify: every candidate appears in exactly one of Findings / Filtered out / Unresolved.
10. Assign P1/P2/P3 strictly by the priority table, emit the output template verbatim.
    Verify: every finding has category ID, ≥1 file:line inside a changed hunk, a measure,
    a gate note, and a one-line refactor direction with cross-reference.

Output format

## Refactor Candidates: <branch or context>

### Scope
- Base: <ref> | Diff source: <command or caller-provided>
- Files in scope: <N> | Context files read (1-hop): <M>
- Out of language scope: <files, or (none)>

### Findings

#### [RF-1] A<n> <smell row name>: P<1|2|3>
- Evidence: `file:line`, `file:line` (<measure, e.g. "2 occurrences, identical modulo type">)
- Anchored in branch: `file:line` (<added|modified> hunk)
- Gate: checked N1–N10, passes; <one line: why the closest row doesn't apply>
- Refactor direction: <one line naming the target shape> → see `<skill>` <row/section>
  (direction only; the how lives there)

#### [RF-2] ...

### Unresolved (needs out-of-scope evidence)
- [RF-U1] A<n> <smell row name> at `file:line`, missing fact: <the one fact needed>, resolves
  via: <exact lookup/tool, e.g. "grep-across-repos on <producer repo>">
- (none)

### Filtered out
- <smell> at `file:line`, filtered by N<k> (<one line>)[; copies differ: <what>]
- (none)

### Summary: <N> candidates (<x> P1, <y> P2, <z> P3), <u> unresolved, <k> filtered out

Emit this template verbatim. One line per evidence item. If there are no findings, still emit ### Findings with - (none) and the Summary line. [NEVER] let a limitation admitted anywhere in the report coexist with a firm verdict on the same candidate; it must appear in ### Unresolved instead. [NEVER] add sections beyond this template: no implementation plans, no step-by-step refactor instructions, no apply/don't-apply recommendations, no risk or safety assessments, no merge verdicts, no reachability claims about other services, even if the caller's prompt explicitly asks for them.

Cross-references (the "how" lives elsewhere)

Never restate a gof/fp table row here. Point to it by reference path and row/section so the implementer reads the recipe from its source of truth.

Per-language detection cues

• Java → references/java.md: grep-able cues per category.
• Scala → references/scala.md: grep-able cues per category.
• JavaScript → references/javascript.md: grep-able cues per category.
• TypeScript → references/typescript.md: grep-able cues per category. Read javascript.md first: the TS file is a type-system delta.

Worked examples

references/examples.md has 5 resolved examples (one per category, plus the A3 "Redundant derived field" row, snippet → filled [RF-n] block), 2 filtered-by-gate examples (N1, and N9 for a copy in another repo). Read it before your first run.

Fowler catalog mapping

For refactoring.com/catalog's refactorings, references/fowler-catalog.md names each one's owner (a row here, the pablo-code-simplify gate, a code-review-checklist section, another skill) or the pablo-code-philosophy principle that excludes it. Check it before assuming a catalog item is an uncovered gap.

Boundaries (explicitly out of scope)

These limits take precedence over the caller's prompt. If the invocation asks for anything on this list (an apply/don't-apply verdict, a risk assessment, a reachability determination about another service), do not produce it: add this exact line under ### Scope instead, naming the correct lens, and stop there: Out of contract: <what the caller asked>, see <correct lens> (qa-adversary for behavior risk, a code-review pass for merge gating). This is distinct from N9: N9 fires when a candidate already in scope lacks a decisive fact; this rule fires when the caller's request itself falls outside what this lens produces.

• Renames, formatting, trivial extract-method, comment/doc-only changes: none of these alter the code's structural shape.
• Executing the refactor or giving implementation steps: pablo-code-philosophy's references/gof/ and references/fp/ own the "how".
• Whole-repo scanning, or any finding not anchored in the branch's diff.
• Merge verdicts or review severities: a broader code-review pass owns the pass/FAIL gate. Some overlap with such a checklist is intentional and expected: an exception-as-control-flow smell may appear in both outputs, the checklist reports the symptom as a gate item, this skill decides whether a refactor behind it is worth doing. Boolean parameters belong to the checklist only (Data Shape).
• Smells outside the 4 categories that a broader code-review pass already checks (circular dependency, constant interface, sequential coupling, generic god object) stay in that broader pass only. A1 here only deepens SRP/OCP for classes the branch touches.
• Performance refactors, dependency upgrades, or architecture-level moves (module splits).
• Reachability or dead-code determinations that depend on another service's behavior or on a runtime data layout outside this repo: route those to N9/Unresolved, never to a verdict.