/oma-refactor

name: oma-refactor
description: Restructure existing code while preserving observable behavior. Use
  for targeted technical debt or hotspot work with characterization tests.

Refactor Agent - Behavior-Preserving Restructuring Specialist

Scheduling

Goal

Improve internal code structure - readability first - without changing observable behavior, through small verified transformations, each gated by a safety net (tests / tooling / types) and committed separately from any behavior change.

Intent signature

• User asks to refactor, clean up, restructure, modernize, de-duplicate, or "make this code maintainable/readable".
• User mentions code smells, technical debt, legacy code, long methods/files, god classes, hotspots, characterization tests, or extract/move/rename transformations.
• User asks "where should we refactor first?" or wants a refactoring plan/priority for a codebase.

When to use

• Executing a refactoring on specific files/modules (extract, move, rename, decompose, pattern/idiom alignment)
• Preparatory refactoring before a feature ("make the change easy, then make the easy change")
• Legacy (brownfield) rescue: seam discovery + characterization tests, then restructuring
• Refactoring target selection and prioritization (smells + SATD + hotspot = churn x complexity)
• Auditing whether code is safe to refactor now (coverage breadth x mutation strength x flakiness)

When NOT to use

• Adding or completing behavior already requested by the user -> use the appropriate existing implementation skill; classify the scope under Entry first.
• Fixing a reported bug or failing behavior -> use `oma-debug` (refactoring must not change behavior)
• Security/performance/accessibility review or quality audit -> use `oma-qa`
• System design, module boundary decisions, ADRs, convention changes -> use `oma-architecture` (a convention/pattern change is an architecture decision, not a local refactoring)
• DB schema design or migration mechanics -> use `oma-db` (this skill only plans the expand-contract sequence)
• Commit splitting / staging mechanics -> use `oma-scm`
• Performance optimization as a goal -> out of scope by definition (tuning is a side effect, never the objective)

Expected inputs

• `target`: file/module/path, smell report, SATD marker, or the feature request motivating preparatory refactoring
• `verification`: existing project test command(s); coverage/mutation tooling if already available
• `constraints`: coding guide / conventions, regulated-environment flags, merge-window concerns
• Optional: prior metric reports, hotspot data, ADRs touching the target area

Expected outputs

• Refactored code as a sequence of atomic, refactor-only commits (no test changes mixed in)
• Safety-net additions when missing (characterization / golden-master tests) as separate commits
• Before/after report: metric delta (cyclomatic/cognitive complexity, size, coupling) + readability verdict

outputs:
  - name: report
    description: refactoring plan or before/after report
    artifact: ".agents/results/refactor/*.md"
    required: false

Standalone runs write plan / before-after reports under `.agents/results/refactor/`; orchestrated runs (via the `refactor-engineer` agent) write `.agents/results/result-refactor[-{sessionId}].md` per the agent execution protocol.

Dependencies

• `resources/definition.md` (invariant definition: 5 properties, boundaries, destination principle, naming roles, inline evidence)
• `resources/measurement.md` (4-layer measurement + git forensics commands)
• `resources/governance.md` (optional organization conventions and existing verification tools)
• Configured code-intelligence symbol/reference tools; existing project test runners for the target language
• Git history for churn/ownership/hotspot analysis

Control-flow features

• Branches by safety-net state (greenfield vs brownfield), statefulness (code-only vs expand-contract), and verification outcome (pass vs Mikado revert)
• Reads code/history/metrics; writes code, tests (in separate commits), and reports
• Stops and routes to `oma-architecture` when the change requires a convention/boundary decision

Structural Flow

Entry

1. Classify the requested outcome against the actual target code, not the word "refactor" alone. Behavior-preserving restructuring stays here. Implementation or bug fixing already included in the request continues under the appropriate existing implementation skill or `oma-debug`, within existing authorization and without renewed approval. For mixed requests, separate behavior changes from restructuring and apply this skill only to the latter. 2. For the refactoring scope, establish its motivation and diagnose the safety net: coverage of changed lines, test determinism (flakiness), mutation strength if measurable. 3. Identify the destination form: the language idiom and codebase convention the result must match.

Missing or stub code does not itself authorize new behavior. A pure refactor with no implementation to restructure reports the missing target rather than inventing one. If a contract fact needed for correctness remains unknown after checking available task and project evidence, ask for that specific fact under the shared execution policy and clarification protocol. Distinguish missing information from missing authorization: retain existing permission, pause only dependent work, and continue independent authorized work.

Scenes

1. **PREPARE**: Within the refactoring scope, classify greenfield (safety net exists) vs brownfield (build net first); check size gates and hotspot rank; confirm two-hats scope (no feature/bug work mixed in). 2. **ACQUIRE**: Read target code via symbol tools; collect metrics (complexity, size, coupling) and git signals (churn, ownership); read the coding guide for conventions. 3. **REASON**: Decompose the goal into a sequence of named atomic transformations; for stateful targets plan expand-contract; verify