{"id":"cc823c93-f355-4356-a40c-a7d3e660b8fa","shortId":"AKGcW4","kind":"skill","title":"refactor-plan","tagline":"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.","description":"# Refactor Planning\n\n## Process\n\n### 1. Understand Problem\n- Get detailed description from user\n- Ask about potential solutions they've considered\n- Explore codebase to verify current state\n\n### 2. Define Scope\n- Interview user about implementation details\n- 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.\n- Define exactly what changes and what stays\n- Check test coverage in affected areas\n\n### 3. Break Down Work\nApply Martin Fowler's principle: \"Make each refactoring step as small as possible, so that you can always see the program working.\"\n\n- Create list of tiny commits\n- Each commit leaves codebase working\n- Sequential, not parallel changes\n\n### 4. Create GitHub Issue\n\n```bash\ngh issue create --title \"Refactor: <title>\" --body \"$(cat <<'EOF'\n## Problem Statement\n\nThe problem from the developer's perspective.\n\n## Solution\n\nThe approach from the developer's perspective.\n\n## Commits\n\nDetailed plan broken into the tiniest commits possible. Each leaves codebase working.\n\n1. Add new interface type\n2. Update service to accept new interface (keep old code path)\n3. Add tests for new code path\n4. Update consumers to use new interface\n5. Remove old code path\n\n## Implementation Decisions\n\n- Modules to build/modify and their interfaces\n- Architectural decisions\n- Schema changes\n- API contracts\n\nDo NOT include file paths or code snippets -- they go stale.\n\n## Testing Decisions\n\n- What makes a good test (behavior, not implementation)\n- Which modules need tests\n- Prior art: similar test patterns in the codebase\n\n## Out of Scope\n\nWhat is explicitly not included.\nEOF\n)\"\n```\n\n## Rules\n\n- Each commit must keep codebase functional\n- No implementation details in plan (focus on behavior)\n- Verify test coverage before starting\n- Get user approval on approach\n\n## Error Handling\n\n- `gh issue create` fails -- run `gh auth status` to verify auth; offer to print as markdown instead\n- Test coverage insufficient -- note gaps and add \"add tests for X\" as first commit\n- Scope larger than expected -- revise plan with user before proceeding\n\n## See Also\n\n- [tdd](../tdd/SKILL.md) -- implement refactored code using test-driven development","tags":["refactor","plan","agent","skills","helderberto","agent-skills","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli"],"capabilities":["skill","source-helderberto","skill-refactor-plan","topic-agent-skills","topic-ai-tools","topic-antigravity","topic-claude-code","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-markdown","topic-plugin","topic-sdlc","topic-skills","topic-tracer-bullet"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/helderberto/agent-skills/refactor-plan","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add helderberto/agent-skills","source_repo":"https://github.com/helderberto/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (2,311 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:09:14.295Z","embedding":null,"createdAt":"2026-05-18T13:14:54.595Z","updatedAt":"2026-05-18T19:09:14.295Z","lastSeenAt":"2026-05-18T19:09:14.295Z","tsv":"'/tdd/skill.md':369 '1':50,207 '2':71,212 '3':124,223 '4':164,230 '5':237 'accept':216 'add':208,224,348,349 'affect':122 'also':367 'altern':80 'alway':145 'api':254 'appli':128 'applic':100 'approach':81,83,188,322 'approv':320 'architectur':250 'area':123 'art':282 'ask':58 'askuserquest':102 'auth':331,335 'avail':104 'bash':168 'behavior':274,312 'bodi':174 'break':22,125 'broken':197 'build/modify':246 'cat':175 'chang':25,35,114,163,253 'check':118 'code':34,97,221,228,240,262,372 'codebas':66,158,205,288,303 'commit':28,154,156,194,201,300,355 'consid':64 'consum':232 'contract':255 'coverag':120,315,343 'creat':4,150,165,171,327 'current':69 'decis':243,251,268 'defin':72,111 'descript':55,92 'detail':54,78,195,307 'develop':183,191,377 'direct':36 'driven':376 'eof':176,297 'error':323 'exact':112 'expect':359 'explicit':294 'explor':65 'fail':328 'file':259 'first':354 'fix':41 'focus':310 'fowler':130 'function':304 'gap':346 'get':53,318 'gh':169,325,330 'github':166 'go':265 'good':272 'handl':324 'implement':33,77,242,276,306,370 'includ':258,296 'instead':341 'insuffici':344 'interfac':210,218,236,249 'interview':74 'issu':167,170,326 'keep':219,302 'larg':24 'larger':357 'leav':157,204 'line':40 'list':110,151 'make':133,270 'markdown':340 'martin':129 'mention':21 'modul':244,278 'must':301 'need':16,279 'new':209,217,227,235 'note':345 'number':109 'off':90 'offer':336 'old':220,239 'one':39 'one-lin':38 'option':86 'otherwis':105 'parallel':162 'path':222,229,241,260 'pattern':285 'perspect':185,193 'plan':3,7,13,48,196,309,361 'possibl':140,202 'potenti':60 'present':79,106 'preview':94 'principl':132 'print':338 'prior':281 'problem':52,177,180 'proceed':365 'process':49 'program':148 'refactor':2,6,15,18,47,135,173,371 'refactor-plan':1 'remov':238 'renam':43 'revis':360 'rule':298 'run':329 'schema':252 'scope':73,291,356 'see':146,366 'sequenti':160 'servic':214 'show':96 'similar':283 'singl':45 'sketch':98 'skill' 'skill-refactor-plan' 'small':27,37,138 'snippet':263 'solut':61,186 'source-helderberto' 'stale':266 'start':317 'state':70 'statement':178 'status':332 'stay':117 'step':136 'strategi':19 'structur':5 'tdd':368 'test':119,225,267,273,280,284,314,342,350,375 'test-driven':374 'tini':153 'tiniest':200 'titl':172 'topic-agent-skills' 'topic-ai-tools' 'topic-antigravity' 'topic-claude-code' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-markdown' 'topic-plugin' 'topic-sdlc' 'topic-skills' 'topic-tracer-bullet' 'trade':89 'trade-off':88 'type':211 'understand':51 'updat':213,231 'use':8,31,93,101,234,373 'user':10,57,75,319,363 'variabl':46 've':63 'verifi':68,313,334 'want':11 'work':127,149,159,206 'x':352","prices":[{"id":"f4a3157c-f5d9-4bf9-8dff-b440284866f5","listingId":"cc823c93-f355-4356-a40c-a7d3e660b8fa","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"helderberto","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:54.595Z"}],"sources":[{"listingId":"cc823c93-f355-4356-a40c-a7d3e660b8fa","source":"github","sourceId":"helderberto/agent-skills/refactor-plan","sourceUrl":"https://github.com/helderberto/agent-skills/tree/main/skills/refactor-plan","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:54.595Z","lastSeenAt":"2026-05-18T19:09:14.295Z"}],"details":{"listingId":"cc823c93-f355-4356-a40c-a7d3e660b8fa","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"helderberto","slug":"refactor-plan","github":{"repo":"helderberto/agent-skills","stars":8,"topics":["agent-skills","ai","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli","markdown","plugin","sdlc","skills","tracer-bullet"],"license":"mit","html_url":"https://github.com/helderberto/agent-skills","pushed_at":"2026-05-14T11:37:47Z","description":"My personal SDLC toolbelt for AI coding agents — PRD to ship.","skill_md_sha":"8b253e2e622a6ed0449e4425ca4cec151ebd05a9","skill_md_path":"skills/refactor-plan/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/helderberto/agent-skills/tree/main/skills/refactor-plan"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"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."},"skills_sh_url":"https://skills.sh/helderberto/agent-skills/refactor-plan"},"updatedAt":"2026-05-18T19:09:14.295Z"}}