duck-refactor
Multi-file code restructuring with reference tracking. Use when: "refactor this", "extract this function", "rename this across codebase", "move this to another file", "inline this".
How do I install this agent skill?
npx skills add https://github.com/sprngr/rubber-duck --skill duck-refactorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a robust framework for refactoring code across multiple files, emphasizing safety through explicit planning and user approval. It includes specific guardrails to prevent weakening security controls and requires verification of changes. While it interacts with codebase content, its strict operational boundaries and human-in-the-loop requirements effectively mitigate standard risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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-refactoris multi-file restructuring;duck-patchis single-file bug fix - vs duck-simplify:
duck-refactoris neutral restructuring;duck-simplifyis complexity reduction with specific goal - vs duck-design:
duck-refactoris implementation;duck-designis decision/tradeoff analysis - vs duck-debug:
duck-refactorchanges code;duck-debugonly 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-designfirst -
If refactoring reveals complexity issues, note for
duck-simplifyfollow-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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/sprngr/rubber-duck/duck-refactor">View duck-refactor on skillZs</a>