agentsclimarketplace

Refactor planning

Skill ahtishamshahzad/agent_dev_flow/.ai/skills/refactor-planning

Tool-neutral AI Engineering System: 174 reusable skills (installable as Claude Code plugins) for planning and building software with AI agents. Classify → plan → approve → build under quality gates. Works with Claude Code, Codex, Cursor, Windsurf, Copilot & Antigravity. Canonical in .ai/.

Install
npx -y skills add ahtishamshahzad/agent_dev_flow --skill refactor-planning

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 21 days oldThe repository was created 21 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use to plan a behavior-preserving structural improvement — audit the target, ensure test coverage exists, plan small reversible steps, and verify behavior is unchanged. Any intended behavior change is a feature, not a refactor.

SKILL.md

3.5 KB, as published. Nobody here has run it

Refactor Planning

Purpose

Plan a refactor that improves structure or quality without changing external behavior, in small reversible steps backed by tests. Produces a refactor work item in ../../work-items/refactors/.

When to Use

  • Request classified as refactor, or cleanup enabling later work.
  • Not when behavior should change (that's feature-planning) or when fixing a defect (bug-investigation).

Inputs

  • The target code and its current tests.
  • The improvement goal (readability, decoupling, performance-neutral cleanup).

Discovery Questions

  • What is the concrete improvement goal, and how is "better" judged?
  • Does adequate test coverage exist to prove behavior is preserved?
  • What is the blast radius; who depends on this code?
  • Can it be done in small, independently verifiable steps?

Responsibilities

  • Audit the target and its dependents.
  • Confirm/establish test coverage before touching risky areas.
  • Plan small, reversible, behavior-preserving steps.
  • Define verification that behavior is unchanged at each step.
  • Record the refactor work item.

Required Workflow

  1. Read the target + dependents + tests.
  2. If coverage is inadequate, plan to add characterization tests first.
  3. Break the refactor into small reversible steps.
  4. Define per-step verification (tests green, behavior identical).
  5. Record the work item (steps, risk, verification).

Decision Rules

  • Behavior-preserving by definition — any behavior change reclassifies as a feature.
  • Add tests before refactoring under-covered risky code.
  • Prefer many small steps over a big-bang rewrite.
  • If risk is high and value low, recommend deferring.

Rules

  • Do not change observable behavior.
  • Keep each step independently verifiable and revertible.
  • Preserve public contracts unless the plan explicitly versions them.

Anti-Patterns

  • Big-bang rewrite with no rollback path.
  • Refactoring untested, risky code without adding tests first.
  • Slipping behavior changes into a "refactor."

Validation Checklist

  • Improvement goal explicit.
  • Coverage confirmed or characterization tests planned.
  • Steps small and reversible.
  • Per-step verification defined.
  • Behavior-preservation guaranteed by tests.

Definition of Done

A recorded refactor work item with a clear goal, sufficient test coverage (or a plan to add it), small reversible steps, and per-step verification proving behavior is unchanged.

Related Skills

existing-project-audit, testing-strategy, task-planning, code-review, performance-review (if perf-motivated), project-orchestrator.

Related Knowledge

../../knowledge/ (module contracts, invariants).

Related References

../../references/<topic>/ for patterns if needed.

Context Loading Guidance

  • Requires: target code, dependents, current tests, the goal.
  • Does not require: unrelated modules, the full reference tree, unrelated skills.
  • May load: testing-strategy (coverage), performance-review (if perf-driven).
  • Stop when: steps + verification are recorded.

Token Efficiency Guidance

Scope reading to the target and its direct dependents. Capture steps tersely; rely on tests as the verification record rather than prose.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.