helderberto/refactor-plan
skills/refactor-plan/SKILL.md
Create structured refactoring plans. Use when user wants to plan a refactor, needs a refactoring strategy, or mentions breaking down large changes into small commits. Don't use for implementing code changes directly, small one-line fixes, or renaming a single variable.
$ install --global
skillsauthnpx skillsauth add helderberto/skills refactor-planInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 30, 2026, 2:40 AM6.7s1 file scanned
SKILL.md
- name:
- refactor-plan
- description:
- Create structured refactoring plans. Use when user wants to plan a refactor, needs a refactoring strategy, or mentions breaking down large changes into small commits. Don't use for implementing code changes directly, small one-line fixes, or renaming a single variable.
Refactor Planning
Process
1. Understand Problem
- Get detailed description from user
- Ask about potential solutions they've considered
- Explore codebase to verify current state
2. Define Scope
- Interview user about implementation details
- Present alternative approaches — each approach as an option with trade-offs in description; use preview to show code sketches when applicable. Use AskUserQuestion when available; otherwise present as a numbered list.
- Define exactly what changes and what stays
- Check test coverage in affected areas
3. Break Down Work
Apply Martin Fowler's principle: "Make each refactoring step as small as possible, so that you can always see the program working."
- Create list of tiny commits
- Each commit leaves codebase working
- Sequential, not parallel changes
4. Create GitHub Issue
gh issue create --title "Refactor: <title>" --body "$(cat <<'EOF'
## Problem Statement
The problem from the developer's perspective.
## Solution
The approach from the developer's perspective.
## Commits
Detailed plan broken into the tiniest commits possible. Each leaves codebase working.
1. Add new interface type
2. Update service to accept new interface (keep old code path)
3. Add tests for new code path
4. Update consumers to use new interface
5. Remove old code path
## Implementation Decisions
- Modules to build/modify and their interfaces
- Architectural decisions
- Schema changes
- API contracts
Do NOT include file paths or code snippets -- they go stale.
## Testing Decisions
- What makes a good test (behavior, not implementation)
- Which modules need tests
- Prior art: similar test patterns in the codebase
## Out of Scope
What is explicitly not included.
EOF
)"
Rules
- Each commit must keep codebase functional
- No implementation details in plan (focus on behavior)
- Verify test coverage before starting
- Get user approval on approach
Error Handling
gh issue createfails -- rungh auth statusto verify auth; offer to print as markdown instead- Test coverage insufficient -- note gaps and add "add tests for X" as first commit
- Scope larger than expected -- revise plan with user before proceeding
See Also
- tdd -- implement refactored code using test-driven development
Related Skills
helderberto/teach
tools
VerifiedTrustedCommunity
Teach the user a new skill or concept, within this workspace.
10SKILL.mdUpdated Jun 13, 2026
helderberto/handoff
documentation
VerifiedTrustedCommunity
Compact the current conversation into a handoff document for another agent to pick up.
10SKILL.mdUpdated May 20, 2026
helderberto/caveman
testing
VerifiedTrustedCommunity
Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
10SKILL.mdUpdated May 12, 2026
helderberto/create-skill
development
VerifiedTrustedCommunity
Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill, or asks "make a skill for X".
8SKILL.mdUpdated May 20, 2026