Restructure existing code while preserving observable behavior. Use for targeted technical debt or hotspot work with characterization tests.
77%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.agents/skills/oma-refactor/SKILL.mdImprove 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.
oma-debug (refactoring must not change behavior)oma-qaoma-architecture (a convention/pattern change is an architecture decision, not a local refactoring)oma-db (this skill only plans the expand-contract sequence)oma-scmtarget: file/module/path, smell report, SATD marker, or the feature request motivating preparatory refactoringverification: existing project test command(s); coverage/mutation tooling if already availableconstraints: coding guide / conventions, regulated-environment flags, merge-window concernsoutputs:
- name: report
description: refactoring plan or before/after report
artifact: ".agents/results/refactor/*.md"
required: falseStandalone runs write plan / before-after reports under .agents/results/refactor/; orchestrated runs (via the refactor-engineer agent) write the result report at the path defined by the agent result contract (../_shared/runtime/result-contract.md).
resources/definition.md (invariant definition: 5 properties, boundaries, destination principle, naming roles, inline evidence)resources/measurement.md (4-layer measurement + git forensics commands)oma-architecture for an ADR + ratchet plan.oma-debug; do not fix it in the refactor commit..git-blame-ignore-revs.| Failure | Recovery |
|---|---|
| Tests fail after a transformation | Mikado: record prerequisite, undo only this transformation's edits, preserve unrelated work, attack prerequisite first |
| No tests and code is untestable | Find a seam; apply only minimal mechanical changes to inject test access, then characterize |
| Tests are flaky | Fix or quarantine flaky tests before refactoring - an unreliable net is no net |
| Metric improves but readability worsens | Reject the transformation; readability is the success criterion, metrics are proxies |
| Scope keeps growing | Stop; report the boundary issue and split into a Mikado graph or route to architecture |
| Refactoring engine/codemod produces wrong output | Engines are not infallible - tests re-run is mandatory; fall back to manual atomic edits |
| A pure refactor has no implementation to restructure (missing or stub code) | Report the missing target rather than inventing one; missing or stub code does not itself authorize new behavior |
| 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 |
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 (two hats: no feature or bug work mixed in).refactor: only -> next transformation. This safety-net run is the skill's required verification: perform it when test execution is permitted; when the user or project instructions rule it out, stop before the next transformation and report the applied transformation as unverified.
On repeated failure (Mikado): record the broken prerequisite, undo only this transformation's edits,
preserve pre-existing edits and other contributors' concurrent work, recurse on the prerequisite first.Reads target source, tests, the coding guide, lint configs, and git history. Mutates production code (structure only) and adds tests in separate commits. Runs test runners, coverage/mutation tools, codemod engines, and git log analysis. May write reports under .agents/results/refactor/ and entries to .git-blame-ignore-revs. Never alters observable behavior, public contracts, or persisted data without an expand-contract plan.
Local code tools: ../_shared/core/code-intelligence.md (code search/navigation)
Authorization and contract ambiguity: ../_shared/core/execution-policy.md and ../_shared/core/clarification-protocol.md (when clarification or authorization is needed)
Invariant definition (5 properties, boundaries, destination, naming roles, contexts, D&C, inline evidence): resources/definition.md
Measurement: 4 layers + git forensics commands: resources/measurement.md
Context loading: ../_shared/core/context-loading.md
Quality principles: ../_shared/core/quality-principles.md
Adjacent skills: oma-debug (bugs), oma-qa (audits), oma-architecture (boundaries/ADR), oma-db (schema), oma-scm (commits)
first-fluke/oh-my-agent
2bd468c
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.