Panda Suite Docs
v1.9.2GitHub ↗
Panda Suite / Panda Refactor

Panda Refactor

Examples use standalone Codex names. For a Codex plugin, use $panda-suite:panda-refactor; for a Claude Code plugin, use /panda-suite:panda-refactor. See all invocation formats.

Panda Refactor carries a bounded structural improvement from evidence to verification while preserving observable behavior and supported contracts. It combines complexity assessment, planning, incremental edits, and testing around the behavior that must stay stable. It is complete on its own.

At a glance

Topic Summary
Use it for Splitting responsibilities, removing duplication, untangling dependencies, moving module boundaries
Not for Diagnosing a defect (Debugger) or measured speedups (Perf)
Edits by default Depends on the request: analysis and planning are read-only; "refactor X" authorizes scoped edits
Check results PASS, FAIL, NOT RUN, BLOCKED, with reasons
Valid result "No change needed", with justification

Request types

Mode names are optional; Refactor infers them from your wording.

Request Deliverable and editing boundary
ANALYZE Evidence-backed findings and priorities; source and tests unchanged
DESIGN Current and proposed responsibilities, alternatives, trade-offs; only a requested artifact is written
PLAN Incremental plan with files, prerequisites, invariants, checks; no source or test edits
EXECUTE Scoped code and test changes with baseline and incremental verification
REVIEW Compatibility and correctness findings on a refactor diff; read-only unless repairs are requested
QUICK A depth modifier; it keeps the requested outcome's permissions and necessary checks

The preservation loop

  1. Discover the problem and contract. Responsibilities, public entry points, consumers, inputs/outputs, errors, permissions, state, side effects. Complexity costs are concrete, not stylistic.
  2. Define invariants and resolve contradictions. Each material behavior maps to evidence and a check. If current behavior violates requirements, that pre-existing defect is disclosed: preserving it and fixing it are different outcomes, and a characterization test must not quietly make it a contract.
  3. Choose the smallest useful structure. No change, a minimal improvement, and a larger alternative are compared only when the decision warrants it. Abstractions need real coupling or variation to justify them.
  4. Establish a baseline. Relevant checks run before any edit; pre-existing failures are recorded. Discriminating tests are added for meaningful gaps when authorized.
  5. Implement and verify in increments. One coherent change, inspect the diff, run checks, reconcile invariants, then the next change. Tests are never weakened to reach green.
  6. Check completion and stop. Final diff, affected consumers, and the invariant-to-check map. Differential equality can preserve an existing bug; passing tests bound confidence to exercised behavior.

For public API moves, state or transaction changes, concurrency, or conflicting sources, Refactor reads its compatibility guidance.

Examples

Refactor with full verification

$panda-refactor Refactor src/messages to remove forwarding layers. Preserve the
public imports, permission checks, error behavior and exact output. Run baseline
checks, make small changes, and report actual verification and remaining gaps.

Analysis only

$panda-refactor Analyze src/messages; do not edit.

Plan only

$panda-refactor Plan the extraction of tax rules from src/checkout into their own
module; do not implement.

A persisted plan defaults to .panda-suite/plans/YYYY-MM-DD-<topic>.md.

Compare designs

$panda-refactor Compare two ways to split the 1,200-line OrderService: by use case
or by aggregate. Show current and proposed responsibilities and trade-offs.
Write the comparison to docs/order-service-design.md only.

Move a public module safely

$panda-refactor Move utils/dates.py to core/time/dates.py. External packages import
the old path, so keep a compatible re-export. Run the tests and a check that the
old import still works.

Review a refactor diff

$panda-refactor Review this branch, which claims to be a pure refactor of the
billing module. Flag any observable behavior change. Read-only.

Quick bounded edit

$panda-refactor Quick: extract the duplicated retry loop in src/clients/a.py and
src/clients/b.py into one helper. Run the client tests.

"Quick" reduces depth, not contract checks.

When existing behavior is wrong

$panda-refactor Restructure src/discounts. Note: I think stacking two coupons is
currently allowed even though the policy forbids it.

Expect the pre-existing defect to be disclosed and a decision requested before any behavior change; the structural work continues independently.

Optional peer guidance

Refactor may load Simplify, Plan, Execute, Test, Impact, or Review guidance when deeper help is useful. None is required, and missing peers never block the workflow. At commit time it uses Git guidance; implementation never authorizes commits or pushes.

Skill instructions

Read the full Panda Refactor instructions in the repository.