Hatch3r Refactor

---
id: hatch3r-refactor
name: hatch3r-refactor
type: skill
description: Internal code quality improvement workflow without changing external behavior. Use when refactoring code structure, simplifying modules, or improving maintainability.
tags: [implementation, orchestration]
quality_charter: agents/shared/quality-charter.md
efficiency_patterns: agents/shared/efficiency-patterns.md
cache_friendly: true
---
> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool when your project uses a different package manager.

# Code Refactor Workflow

## Quick Start

```
Task Progress:
- [ ] Step 0: Detect ambiguity (P8 B1)
- [ ] Step 1: Read the issue, specs, and existing tests
- [ ] Step 2: Produce a refactor plan
- [ ] Step 3: Implement with behavioral preservation
- [ ] Step 4: Verify all tests pass, add regression tests
- [ ] Step 5: Open PR
```

## Step 0 — Detect Ambiguity (P8 B1)

Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: refactor scope (one module vs cross-cutting), behavioral invariants to preserve, public API surface (preserved vs changed), test rewrite policy (preserve vs replace), and acceptable performance delta.

## Fan-out Discipline (P8 B2)

Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.

## Step 1: Read Inputs

- Parse the issue body: motivation, proposed change, affected files, safety plan, risk analysis, acceptance criteria.
- Read project quality standards documentation.
- Read specs for the area being refactored.
- Review all existing tests — every one must still pass after refactoring.
- **Review reference implementations**: If the orchestrator provided `similar-implementation` researcher output, read the reference implementations and their extracted conventions. The refactored code should align with these established codebase patterns.
- **Review resolved requirements**: If the orchestrator provided `requirements-elicitation` answers, use them to understand explicit user decisions on behavioral invariants and scope.
- For external library docs and current best practices, follow the project's tooling hierarchy.

## Step 2: Refactor Plan

Before changing code, output:

- **Goal:** what improves (readability, performance, maintainability)
- **Strategy:** how the refactor works
- **Convention alignment:** which reference implementation's patterns the refactored code will follow (from `similar-implementation` output), with divergences noted. If no reference was provided, note "using existing codebase conventions."
- **Files to modify:** list with what changes
- **Behavioral invariant:** what must NOT change
- **Risk assessment:** what could go wrong, how to detect
- **Rollback:** how to revert if needed

## Step 3: Implement

- Refactor with minimum changes needed.
- Preserve all public interfaces and external behavior.
- Remove dead code created by the refactor.
- Do not introduce new dependencies.
- If a bug is found, document it -- fix in a separate PR.
- **Error handling preservation.** When moving or restructuring error handling code, verify that the error behavior is preserved. A common refactoring mistake is accidentally changing error types, removing error context, or altering error propagation paths. Run error-path tests after each structural change.

## Step 4: Verify

- All existing tests must pass without modification.
- Add regression tests for previously untested at-risk behavior.
- Performance verification if refactored code is on a hot path.

```bash
${HATCH3R:VERIFY_GATE_ALL}
```

Resolved to the project's language-aware gate at sync time (fallback when detection is unknown: `npm run lint && npm run typecheck && npm run test`).

## Step 5: Open PR

Use the project's PR template. Include:

- Motivation (why this refactor now)
- Before/after structure (high-level description)
- Proof of behavioral preservation (test results)
- Performance impact (if applicable)

## Required Agent Delegation

> **Note:** When this skill is invoked via the orchestration pipeline (board-pickup or workflow commands), skip this section — the orchestrator handles agent delegation in Phases 3 and 4.

You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:

- **`hatch3r-researcher`** — MUST spawn before implementation with modes `current-state`, `refactoring-strategy`, `migration-path`. For Tier 2+ tasks (per `hatch3r-deep-context`), also include `similar-implementation` (refactors benefit most from convention alignment — ensures the refactored code follows established patterns) and `requirements-elicitation`. Skip only for trivially simple refactors (`risk:low` AND `priority:p3`).
- **`hatch3r-reviewer`** — MUST spawn after implementation for code review, verifying behavioral preservation.

## Related Skills

- **Skill**: `hatch3r-logical-refactor` — use when the refactor changes internal logic flow while preserving external behavior
- **Skill**: `hatch3r-visual-refactor` — use when the refactor targets UI/styling changes without altering functionality

## Error Handling

- **Existing tests fail after refactor**: Do not modify tests to make them pass unless the test was verifying an implementation detail (not behavior). If a behavioral test fails, the refactor changed external behavior and must be revised.
- **Refactor scope expands beyond the original module**: If additional modules need changes due to coupling, stop and assess whether the refactor should be split into phases. Get confirmation before expanding scope.
- **Type errors after restructuring**: Resolve all type errors before running tests. If the type system reveals unexpected dependencies, document them as findings for the codebase health record.

## Definition of Done

- [ ] All existing tests pass without modification
- [ ] Regression tests added for at-risk behavior
- [ ] No new linter warnings
- [ ] Performance budgets maintained
- [ ] Dead code removed
- [ ] No external behavior changed
- [ ] No new dependencies introduced