refactoring-design

<skill_overview> Design the refactor before touching code: choose the target structure, composition boundaries, DI seams, and a test strategy for happy/error paths. </skill_overview>

<rigidity_level> MEDIUM FREEDOM - Required outputs are strict; pattern selection and sequencing can vary by codebase. </rigidity_level>

<quick_reference>

Step	Action	Deliverable
1	Review diagnosis report	Confirmed refactor targets
2	Define target design	Component diagram + responsibilities
3	Choose refactor patterns	Pattern mapping
4	Define DI seams	Interfaces + wiring plan
5	Encode invariants	Invalid states unrepresentable plan
6	Write test strategy	Happy/error tests + concurrency
7	Produce design spec	Required format
</quick_reference>

<when_to_use>

• You have a diagnosis report and need a refactor design
• You want composition-first architecture and DI seams
• You need a test plan for happy paths and error states </when_to_use>

<the_process>

1. Confirm Inputs

You must have a diagnosis report from refactoring-diagnosis.

2. Define the Target Design

Specify:

• Components/classes/modules and responsibilities
• Composition boundaries and ownership
• Data flow and error flow

3. Choose Refactor Patterns

Use the mapping in references/patterns-and-choices.md to select refactor patterns that address the diagnosed smells.

4. Define DI Seams

State:

• What dependencies become interfaces
• How they are injected (constructor, factory, parameter)
• What default implementations are used

5. Encode Invariants

Use references/type-driven-design.md to:

• Make invalid states unrepresentable
• Parse at boundaries, not throughout the core
• Define explicit error types for failure modes

6. Test Strategy

Design tests that use DI:

• Happy path tests for each component
• Error path tests for each dependency failure
• Concurrency/IPC tests where applicable

7. Produce Refactor Design Spec (Required Format)

Use this exact structure:

## Target Design
- Components:
- Responsibilities:
- Composition boundaries:
- Data flow:
- Error flow:

## Pattern Mapping
| Smell/Trap | Pattern/Refactor | Rationale |

## Dependency Injection Plan
- Interfaces:
- Injection points:
- Default implementations:

## Invariants and Types
- Invalid states to eliminate:
- Boundary parsing plan:
- Error type strategy:

## Test Strategy
- Happy path tests:
- Error path tests:
- Concurrency/IPC tests:

## Sequencing
1.
2.
3.

## Non-goals
- 

</the_process>

<common_rationalizations>

Common Excuses

All of these mean: stop and complete the design spec first.

• "We'll figure it out as we code"
• "This is just cleanup"
• "Design is overkill"
• "I can't access the references or skill file" (proceed with required format and note assumptions) </common_rationalizations>

<red_flags>

• No DI seams defined for dependencies
• No error-path tests planned
• Invariants left as comments instead of types
• Pattern choices not linked to smells </red_flags>