Skip to content

donaldfilimon/abi / .agents/skills/refactor

refactor

Verified

Plan, execute, and validate a codebase modernization or refactor with clean-slate thinking while preserving semantics. Use when the user asks how to approach a rewrite vs incremental change or what the risk is (strategy), is ready to apply a refactor plan safely (implementation), or asks whether a refactor broke anything or is complete (validation).

Refactor

One skill, three phases (merged from the former refactor-strategy, refactor-implementation and refactor-validation skills on 2026-09-21). Run the host gate before and after.

Host gate means the repository's own full gate, named in its AGENTS.md/CLAUDE.md. In abi (/Users/donald/sources/repos/abi) that is ./tools/check.sh (it drives ./tools/cargo.sh; never invoke bare cargo there); hand-run cargo test there needs < /dev/null. A bare cargo test is not a gate: in a default-members workspace it can run zero tests and pass.

Phase 1: strategy

Use when: This skill should be used when the user asks how to approach a modernization — e.g. 'should we rewrite or do this incrementally', 'plan a refactor of X', 'what's the risk here' — at the start of significant work.

Provides structured approaches for modernizing codebases using clean-slate thinking while preserving semantics.

When to use

Apply this skill at the beginning of any significant modernization effort.

Core Principles

  • Always start by defining the ideal modern implementation ("what would this look like written today?").
  • Identify invariants and behavioral contracts that must be preserved.
  • Choose strategy based on risk, size, and coupling: incremental, strangler-fig phased, or full rewrite of a module.
  • Produce a concrete plan with milestones, validation gates, and rollback options.

Recommended Process

  1. Capture current behavior and success criteria (tests, contracts, SLAs).
  2. Sketch the ideal modern design (modules, types, error handling, concurrency model, APIs).
  3. Perform gap analysis between current and ideal.
  4. Decide transformation strategy:
    • Small/low-risk → direct rewrite of the module.
    • Large/high-risk → phased (strangler fig, parallel implementation, feature flags).
  5. Define validation criteria for each phase (parity tests, property tests, performance budgets).
  6. Document the plan with clear "Definition of Done" for each step.

Clean-Slate Mindset

When designing the target:

  • Use current language idioms and stdlib features.
  • Prefer explicit over implicit.
  • Design for testability and observability from day one.
  • Eliminate accidental complexity introduced by historical constraints.
  • Choose composition and clear boundaries.

Additional Resources

  • references/strategy-guide.md — detailed decision trees and examples of each strategy.
  • examples/sample-plan-outline.md — real plan outlines from previous modernizations.

Use this skill before touching code. Always run the host gate (see above) before and after.

Optional host settings

For repo-local strictness (focus areas, gate list, claims discipline), copy the example template from the modern-refactor package to the host project as an optional Claude-side local override file (host-side only; this skill does not ship or auto-load host overrides).

Phase 2: implementation

Use when: This skill should be used when the user is ready to execute a refactor plan and asks how to apply it safely — e.g. 'implement this modernization plan', 'extract this safely', 'how do I cut over without breaking things'.

Safe transformation techniques for applying modern designs while preserving behavior.

Principles

  • Write modern impl beside old (parallel) when risk high.
  • Use strangler fig for gradual cutover.
  • Validate at each step with the host gate, parity, contracts.
  • Prefer direct boring code.

Additional Resources

  • references/implementation-playbook.md
  • examples/parallel-extract-outline.md

Pair with the Rust-aware abi or refactor-planner agent for larger modules.

Phase 3: validation

Use when: This skill should be used when the user asks to verify a refactor is done correctly — e.g. 'did I break anything', 'is this refactor complete', 'validate this change meets modern standards' — as the final gate.

Validation layers for modernization: behavioral parity, modern quality, structural.

Layers

  • Behavioral: contracts, tests, host gate, check-parity pass.
  • Modern: apply patterns from modern-patterns, no legacy smells.
  • Structural: boundaries clean, no god files, explicit over implicit.

Additional Resources

  • references/validation-checklist.md

Run the validation skill plus a Rust-aware abi or refactor-planner agent review as the final step.

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 implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall