hashgraph-online/awesome-codex-plugins / plugins/boshu2/agentops/skills/refactor
refactor
VerifiedRestructure or clean up code with no behavior change, proved by before-and-after checks. Use when: asked to clean up, extract, dedupe or simplify, even one function.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.6 KB |
| references/behavior-preserving-simplification.md | markdown | 6.1 KB |
references/behavior-preserving-simplification.md
View on GitHub# Behavior-Preserving Simplification
Use this reference when `/refactor` is asked to simplify code, remove AI-writing artifacts, reduce indirection, or make a module easier to maintain without changing behavior.
## Contract
The external behavior must remain the same. The refactor `SKILL.md` owns what counts as behavior, the procedure and the report shape. A bug found on the way is reported separately for the caller, not fixed inside the refactor.
## What is not prose to tidy
- A comment that a tool reads is code: build constraints, compiler directives, lint or type suppressions, doctests and generated-file markers stay.
- User-visible messages are behavior (SKILL.md, What counts as behavior).
## Red Flags
- Tests need broad rewrites to pass.
- The new abstraction has no second use or clear contract (the report's `abstraction:` line names it).
- The simplification deletes context that future maintainers need.
---
**Source:** Adapted from an external skill corpus / `simplify-and-refactor-code-isomorphically` and `de-slopify`. Pattern-only, no verbatim text.
## Refactoring Catalog
Use these patterns only after the procedure has recorded a baseline, named the observable behavior, and chosen one transformation.
### Extract Method
Use when a function contains a cohesive block with clear inputs and outputs that reads as one named step.
Safety checks:
- pass shared locals explicitly or return values;
- preserve error propagation and cleanup order;
- document side effects and mutation ownership;
- reject an extraction that merely moves complexity behind an opaque name.
### Move, or Extract Module or Class
Use when code sits in a module that does not own its concern, a file owns multiple unrelated concerns, or a cohesive type has a stable boundary.
Safety checks:
- map imports before moving code and reject circular dependencies;
- expose package-level state deliberately rather than duplicating it;
- preserve initialization order, registration, reflection, and serialization names;
- run callers in every affected package, not only the extracted unit.
### Rename
Use when a name is misleading, ambiguous, or hides domain meaning.
Safety checks:
- use language tooling where available and search every tracked reference;
- include strings, configuration, docs, tests, generated surfaces, and scripts;
- treat exported symbol, CLI, JSON, database, metric, and event names as public API;
- avoid preference-only churn that does not improve comprehension.
### Inline
Use when a single-use helper or temporary adds indirection without a contract.
Safety checks:
- preserve evaluation count and order;
- make sure the inlined expression has no hidden side effect;
- reject inlining that duplicates behavior or makes the caller harder to test.
### Simplify Conditional
Use guard clauses, early returns, or table-driven logic when nesting obscures mutually exclusive behavior.
Safety checks:
- preserve branch priority, error identity, logging, and side-effect order;
- add characterization tests for each moved condition before the change and include them in the step-2 baseline;
- do not replace explicit domain states with a clever boolean expression.
### Reduce Parameters
Use an options or request type when parameters travel together and form one concept.
Safety checks:
- update every caller and preserve defaults;
- distinguish required fields from optional zero values;
- avoid a generic bag that hides unrelated responsibilities;
- preserve public API compatibility or make migration explicit.
### Encapsulate
Use when callers read or write a field or shared state directly and one owner should guard its invariants.
Safety checks:
- find every direct reader and writer, including reflection, serialization and tests;
- keep serialized and persisted names, defaults and zero values unchanged;
- narrowing an exported symbol's visibility is an interface change (SKILL.md, What counts as behavior): keep it reachable or report it.
### Substitute Existing Code
Use when local code redoes what the repository already defines (a helper, constant, enum or type) or what the standard library, runtime or framework provides.
Safety checks:
- find the existing symbol and name it in the report;
- show equivalence for the inputs this code actually receives: ordering of equal elements, locale and case rules, rounding, encoding, and how each value type serializes;
- replace a raw literal with a constant or type only when the emitted value stays identical;
- when a framework or downstream layer already performs a step, delete only that step and keep any transformation it does not do; a protective check (SKILL.md, What counts as behavior) stays even then;
- a branch that a removed guard or filter now lets through is live code; check it rather than treat it as dead.
### Remove Dead Code
Use static analysis plus repository-wide search. For CLI commands, flags, or cross-language surfaces in the AgentOps repository, run the following; elsewhere, search every tracked file with the repository's own tools:
```bash
bash scripts/check-removed-symbol-refs.sh -- <removed-command-or-flag>
```
Safety checks:
- rule out reflection, string dispatch, interfaces, plugins, build tags, generated callers, and external packages;
- search source, shell, workflows, docs, skills, and tests;
- the checker already excludes `CHANGELOG.md`, `docs/releases/**`, `.agents/**`, `worktrees/**` and `.worktrees/**`; keep any remaining hit blocking, and add no `--exclude` without justifying it in the summary;
- an alias, adapter or old field that only bridges a shape from earlier in the current unmerged work is not a public interface when the base branch and every release lack that shape and no dependent branch or stored data uses it. Remove it when every caller update fits the scope; otherwise report it. A shape that ever merged or shipped keeps its compatibility contract.
### Complexity
Cyclomatic complexity is at most a signal inside the area the caller selected, never a reason to pick a target or a success metric. A refactor is better only when the behavior proof remains green and the resulting boundary is easier to understand, test, and change.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |