duck-refactor

Structured refactoring 🦆. Multi-file restructuring with reference tracking.

Purpose

Support code restructuring through bounded refactoring operations with explicit reference tracking and verification.

Philosophy Guardrails (skill-local)

Inherit shared guardrails from references/GUARDRAILS.md.

Comment and Documentation Integrity

Document durable constraints, invariants, contracts, and behavior.
Do not narrate development history in code comments or ordinary documentation.
Remove or flag rejected approaches, “this used to be” history, recent-change context, and references to reviews, tests, or sessions when they only explain how the change was produced.
Do not preserve session-only decisions, approval flags, or temporary markers in durable artifacts.
Keep historical context only in a durable artifact intended for history, such as an ADR or changelog.
Keep test or review references only when they state a durable constraint or verification requirement.

Skill-specific delta:

Multi-file refactoring operations require execution approval with full reference tracking.
Distinguish from single-file patches and complexity reduction.

Activation

Use when user asks to refactor, extract, rename across files, move code, inline, or convert patterns.

Trigger phrases:

"refactor this"
"extract this function/class/method"
"rename this across the codebase"
"move this to another file"
"inline this function"
"convert this callback to promise"

Method

Subagent execution mode

When running as a subagent without a user channel (e.g., via duckling): do not apply edits or run verification commands. Execute steps 1-5 as analysis; replace step 6 "execute refactoring" and step 7 "verify" with approval-package content: the derived per-file change plan (diff blocks where applicable) and verification plan. Emit per the host wrapper's contract (preflight + diffs + approval ask + status footer).

1. Clarify refactoring scope

ask 1-3 targeted clarifying questions when context is incomplete
state assumptions explicitly when evidence is missing

Ask one scoping question if any detail unclear:

What to extract/rename/move/inline?
Target destination (new file, existing file, new function name)?
Scope boundaries (this module, whole codebase)?

2. Trace references and dependencies

Use read-only evidence gathering (similar to duck-debug trace mode):

Locate all usages of target code
Map imports/exports
Identify callers and callees
Find test files that reference target
Note external dependencies

Output: "Found N references across M files: [list]"

3. Present refactoring plan

Before any edits, present bounded plan:

Format:

Refactoring plan:
- Operation: [extract function / rename / move / inline / convert]
- Target: [current name/location]
- Destination: [new name/location]
- Target phase: [Phase 1 stubs/interfaces | Phase 2 wiring/integration | Phase 3 concrete implementation]
- Files affected: [bounded list for selected phase]

Changes:
1. [file A]: [change description]
2. [file B]: [change description]

Verification: [tests to run, imports to check]

If phase cap or review-fatigue trigger is exceeded: "This refactoring exceeds current phase bounds. Split into smaller bounded refactorings?"

4. Apply Duck Ladder

Before proposing refactoring approach:

No change needed (YAGNI)
Reuse existing local helper/pattern
Replace with stdlib/native
Use already-installed dependency
Shrink to smallest safe diff
Only then add new code/abstraction

Ask: "Does existing code/pattern already solve this? Can we reuse instead of restructure?"

5. Require execution approval

Before executing refactoring:

Target phase (Phase 1/2/3)
Target files (bounded for selected phase)
Expected structural change (what moves where)
Verification plan (tests, imports, type checking)

Use execution approval flow:

Reply with "approve" to execute this refactoring.
Wait for explicit approval
Do NOT proceed with multi-file refactoring without approval

6. Execute refactoring

After approval:

Make changes in order (definitions before usages, imports before code)
Update imports/exports
Maintain consistent formatting
Preserve accurate comments and documentation that record durable constraints, invariants, contracts, or behavior. Rewrite development narration and session-only decision references when the refactor exposes them.

7. Verify refactoring

Run verification plan:

Tests still pass
No broken imports
Type checker passes (if applicable)
Functionality unchanged

Report: "Refactoring complete. Verification: [test results]. [N] files changed."

Boundaries

Distinguish from other skills:

vs duck-patch: duck-refactor is multi-file restructuring; duck-patch is single-file bug fix
vs duck-simplify: duck-refactor is neutral restructuring; duck-simplify is complexity reduction with specific goal
vs duck-design: duck-refactor is implementation;duck-design is decision/tradeoff analysis
vs duck-debug: duck-refactor changes code; duck-debug only traces/investigates

What duck-refactor does NOT do:

Single-file edits without restructuring -> use duck-patch
Complexity reduction as primary goal -> use duck-simplify
Architecture decisions -> use duck-design
Just moving files without code changes -> use duck-patch

Scope limits:

Phase caps (default): Phase 1 up to 6 files, Phase 2 up to 4 files, Phase 3 up to 2 files
If phase caps or review-fatigue triggers are exceeded, split into smaller bounded approvals
If refactoring requires design decisions, pause and route to duck-design first
If refactoring reveals complexity issues, note for duck-simplify follow-up
If a change would weaken trust-boundary validation, security controls, data-loss prevention, accessibility requirements, or explicit user requirements, refuse it and offer only a safe alternative preserving the constraint.