nicolas-codemate/architect-refactor

Architect Refactor Skill

This skill is for architecture-level refactoring. Not for bug fixes, not for features, not for single-file polish. Use it when the job is to restructure how things fit together.

When to Use

Trigger this skill when:

• The user asks to "decouple", "refactor", "restructure", "reorganize", "redesign"
• A ticket touches a family of similar classes/components (not just one)
• An interface, abstract class, or pattern needs to evolve
• Naming feels wrong across a set of files
• The user says things like "factoriser", "découpler", "renommer l'architecture"

Do NOT use for:

• Single bug fixes
• Adding a feature to an existing well-designed module
• Simple renames of a single symbol
• UI tweaks
• Documentation-only changes

---

The Core Rule

DO NOT WRITE A SINGLE LINE OF CODE BEFORE THE 7 PHASES BELOW ARE COMPLETE.

This skill exists because micro-iterations during refactoring waste massive amounts of time. One clear plan up front beats 40 commits of corrections.

---

Mindset

Before starting, internalize these principles. They are non-negotiable:

1. The ticket is a starting point, not a boundary

A ticket like "Decouple X from Y" describes a symptom. Your job is to find the disease. The disease is almost always bigger than the ticket.

Ask yourself:

• Does the ticket describe the real problem, or just the visible part?
• Is X really the only thing coupled to Y, or is it a family?
• Would fixing only X leave the architecture inconsistent?

2. Take a step back. Abstract away from what exists

Pretend the current code doesn't exist. Ask:

• If I were building this from scratch today, what would it look like?
• What are the real domain concepts?
• What names would I use?
• What would the ideal interface be?

Then compare with reality. The gap is the refactoring scope.

3. Don't be afraid to recreate everything

If the right answer is "throw away 3 classes and make 1 new one", say so. Do not compromise by keeping legacy abstractions "because they exist". Existence is not a justification.

Cheap compromises to refuse:

• "Strangler Fig" as an excuse for duplication
• "It's out of scope" as an excuse to leave a mess
• "It works, so leave it" as an excuse to avoid naming fixes
• "Backward compatibility" when nothing external consumes it

4. The constraint is not the scope. The constraint is the architecture

The ticket scope is a hint, not a cage. If respecting the ticket scope produces bad architecture, the architecture wins. The ticket was written by someone who saw one symptom; you see the whole system.

5. Big picture first, details later

Resist the urge to start coding the first phase. Resist the urge to "just get started". The 30 minutes spent on deep analysis save 4 hours of micro-iterations.

---

The 7 Mandatory Phases

Phase 1 — Family Discovery

Find ALL the code that shares the pattern being refactored, not just what the ticket mentions.

Actions:

1. Read the ticket
2. Identify the central concept (class, interface, pattern)
3. Grep the codebase for all consumers, implementations, similar patterns
4. List every file that is part of the "family"
5. Build a dependency graph of the family

Output: A written inventory of the family. Example:

Family: query builders for server-side tables
- 1 interface (NativeQueryBuilderConfiguratorInterface)
- 1 concrete builder (DatatableQueryBuilder)
- 7 resolvers using it (GetInvestments, GetAccounts, ...)
- 8 configurator implementations
- 1 external consumer (FilterTypeResolver)

RULE: You cannot proceed to Phase 2 until this inventory is complete.

---

Phase 2 — Pattern & Duplication Inventory

Look at the family with fresh eyes. Where are the duplications? Where are the inconsistencies?

Actions:

1. Diff each member of the family against the others
2. Identify methods/blocks that are copy-pasted with minor variations
3. Identify abstractions that have only one child (= useless abstractions)
4. Identify methods in the interface that are identically implemented everywhere
5. Identify naming inconsistencies across the family

Output: A list of smells. Example:

- 5 query builders with ~80 lines of identical plumbing (getBaseQueryBuilder, handleSearch, addJoin)
- Abstract class with only one concrete child (= dead abstraction)
- `getAllSearchableColumns` implemented identically in 5 classes
- Namespaces: 3 files in `Datatable/`, 2 in `Query/`, 1 in `Service/` (inconsistent)
- Method names: `invoke`, `invokeV1`, `invokeV2`, `invokeAgGrid` (inconsistent)

RULE: If this list is empty, the refactoring is probably smaller than you think. Re-read the ticket.

---

Phase 3 — The 10 Mandatory Questions

Answer these before proposing any architecture. Do not skip any.

1. How many consumers of this pattern exist? (Not "how many does the ticket mention" — how many exist in total.)
2. Do they really share the same logic, or just look similar? (If they differ, what differs?)
3. Could a single component replace N components? (If yes, is there a reason not to?)
4. Do the current names reflect the real domain concept? (Or are they technical leftovers?)
5. Is there any abstraction with only one child? (If yes, is the abstraction earning its keep?)
6. Are all interface methods used by all implementers? (If not, why are they in the interface?)
7. Does the ticket describe the real problem, or a symptom? (Dig one level deeper.)
8. What trade-offs are we willing to accept? (Duplication? Coupling? Complexity?)
9. Where should this live in the architecture? (Domain? Infrastructure? Shared kernel?)
10. Is this a surgical refactor or a full redesign? (Be honest. The answer determines everything.)

RULE: Write the answers down. Do not hand-wave. If you can't answer a question, that's a sign you need more discovery — go back to Phase 1.

---

Phase 4 — Target Architectures (2–3 options)

Do NOT propose a single plan. Propose 2 or 3 target architectures with explicit trade-offs.

Format:

### Option A — Minimum viable
- Changes: X, Y
- Trade-offs: accepts duplication in Z, doesn't fix naming
- Effort: small
- Longevity: likely to be re-refactored within 6 months

### Option B — Complete decoupling
- Changes: X, Y, Z, W
- Trade-offs: touches all resolvers, requires doc update
- Effort: medium
- Longevity: stable for years

### Option C — Full redesign
- Changes: new namespace, new interface, new builder, migrate all
- Trade-offs: big churn, requires buy-in from team
- Effort: large
- Longevity: generational rewrite

RULE: Present options with honest trade-offs. Do not pitch. Let the user choose in full knowledge.

---

Phase 5 — Naming Validation (BEFORE any code)

Before writing any code, validate every name with the user:

• Interface name
• Abstract class names
• Concrete class names
• Method names
• Namespace / directory names
• Variable naming conventions

Why before: Renaming is cheap in a text editor, but every rename cascades into imports, tests, docs, and consumers. Validate once, rename never.

RULE: Present the chosen names as a list, get explicit validation, then lock them.

---

Phase 6 — Macro Plan (max 6 steps)

Write a plan with at most 6 steps. If the plan has 15 steps, you did not think enough in Phase 1–4.

Good plan example:

1. Create new interface + shared builder + composition helper
2. Migrate all property-aware resolvers
3. Migrate non-property resolvers (stakeholders, DMS)
4. Delete legacy code (old builder, old interface, dead methods)
5. Documentation pass (single pass, final architecture)
6. Full Behat validation

Bad plan example (DO NOT DO THIS):

1. Create a temporary query builder for Investment
2. Copy logic from DatatableQueryBuilder
3. Add one method to the abstract
4. Wire into GetInvestments resolver
5. Create a query builder for Account
6. ... (15 more steps)

RULE: Micro-steps = insufficient planning. Consolidate. If it's hard, Phase 1–4 were incomplete.

---

Phase 7 — Implementation

Only now, write code.

Rules during implementation:

• Run tests after each macro step, not each file
• Do not touch documentation yet
• Do not rename things again (names were locked in Phase 5)
• Do not expand scope (scope was locked in Phase 4)
• If you find a new issue: note it, do not fix it inline

Documentation pass: After ALL code is stable and all tests pass, do one single documentation pass. Not multiple. One.

---

Anti-Patterns to Refuse

If the user (or you) catches yourself doing any of these, STOP and go back to the appropriate phase.

| Anti-pattern | Fix | |--------------|-----| | Starting Phase 7 before Phase 3 is answered | Back to Phase 3 | | "Let's do the minimum for now and refactor later" | Present Option A/B/C and let user choose | | "This is out of scope" without justification | Re-read the ticket; is it really out of scope or are you avoiding work? | | Creating a class that duplicates another class | Stop. Go back to Phase 2. Find the real abstraction. | | Renaming something during implementation | Stop. Go back to Phase 5. Validate the new name. | | Updating documentation before the architecture is stable | Stop. Doc pass only at the end. | | "Let me fix just this one more thing" | Stop. Note it. Fix it in the planned sequence. |

---

Sanity Checks Before Implementation

Before starting Phase 7, verify:

• [ ] I know every file in the family (Phase 1)
• [ ] I identified all duplications and smells (Phase 2)
• [ ] I answered all 10 questions in writing (Phase 3)
• [ ] I presented 2–3 options to the user (Phase 4)
• [ ] The user chose one option explicitly (Phase 4)
• [ ] All names are validated (Phase 5)
• [ ] The plan has ≤ 6 steps (Phase 6)
• [ ] The plan includes test validation per step (Phase 6)
• [ ] The plan includes a single final doc pass (Phase 6)

If any box is unchecked, do not proceed.

---

Why This Skill Exists

Without discipline, architecture refactoring devolves into 30+ micro-commits, 8 renames, 5 doc rewrites, and a lot of wasted time. The user should not have to drag you back to the big picture at every step.

This skill is a forcing function. It makes you slow down at the start so you can move fast for the rest. The 30 minutes spent on Phases 1–4 save hours of iteration later.

Embrace it. It is not a constraint — it is a tool to protect the quality of your thinking.

Do not fear rewriting everything. If the honest answer is "throw it all out and start over", say so. The worst outcome is a half-refactored codebase that is worse than the original.