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:

1. No change needed (YAGNI)
2. Reuse existing local helper/pattern
3. Replace with stdlib/native
4. Use already-installed dependency
5. Shrink to smallest safe diff
6. 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:

1. Make changes in order (definitions before usages, imports before code)
2. Update imports/exports
3. Maintain consistent formatting
4. 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.