{"id":"dffa842c-613a-4b45-9675-44becf8b141c","shortId":"8V88Wv","kind":"skill","title":"refactor","tagline":"Use when the user asks for a substantial refactor, structural cleanup, or deep codebase improvement beyond a small localized change.","description":"refactor_path = $ARGUMENTS\n\nYou are the team lead for a codebase refactoring. You orchestrate specialists — you don't write production code. Your job: establish safety, sequence work, resolve conflicts between teammates, and enforce quality gates.\n\n## Scope\n\n- No path → refactor entire codebase\n- Path provided → analyze full codebase context, only refactor files within that path\n- `--dimensions` → run only named specialists (e.g., `--dimensions typing,dead-code`)\n- `--phase` → resume from that phase (assumes prior phases completed and committed)\n\n**Branch guard:** If on main/master with no worktree active, STOP — create a worktree or feature branch first. Refactors must be reversible.\n\n## Scaling\n\nAll work flows through teammates. Match pipeline depth to scope:\n\n- **Targeted** (small module, few dimensions): Baseline, spawn 1-2 specialist teammates. Lighter briefing, same team structure.\n- **Module-scoped** (one module, multiple dimensions): Baseline, Phase 1 if structural issues, Phase 2 in parallel. Skip Phase 3 unless cross-cutting issues surfaced.\n- **Full codebase**: All phases, full specialist roster.\n\n## Specialist Teammates\n\nEach agent is a self-contained specialist prompt run in one of two modes:\n- **Analyzer**: Read-only. Produces a findings report. Never edits.\n- **Implementer**: Receives an analyzer report. Executes fixes. Never freelances.\n\nRefactor-local specialists live at `${CLAUDE_SKILL_DIR}/agents/<name>.md`. `typing`, `perf`, and `patterns` delegate to the standalone audit skills at `~/.claude/skills/audit-{typing,perf,patterns}/SKILL.md` — those skills are mode-agnostic, so the prepended mode line is what enforces analyzer/implementer discipline.\n\nTo spawn: read the prompt file, pass its content as the teammate's prompt, prepend mode and scope:\n\n```\nYou are in ANALYZER mode. Scope: <path or \"entire codebase\">. Read-only — produce a findings report, do not edit files.\n<full content of the prompt file>\n```\n\nFor implementer mode, swap the mode line to \"IMPLEMENTER mode — execute fixes from the report below; do not freelance.\" and append the analyzer's findings report.\n\n### Ordering and Rationale\n\n| Agent | Phase | Why This Order |\n|-------|-------|---------------|\n| `dead-code` | 1 — Structural | Deletes files. Must finish before anyone analyzes deleted code. |\n| `structure` | 1 — Structural | Moves/splits/merges files. Must finish before file-local agents start. |\n| `typing` | 2A — First | Types constrain all other agents. Fix types before fixing logic. |\n| `error-handling` | 2B — After types | Needs accurate types to judge error paths. |\n| `correctness` | 2B — After types | Needs accurate types to verify semantic contracts. |\n| `duplication` | 2C — Independent | No ordering dependency. |\n| `perf` | 2C — Independent | No ordering dependency. |\n| `patterns` | 3 — Cross-cutting | Needs stable code to unify patterns across modules. |\n| `security` | 3 — Cross-cutting | Needs stable code to audit boundaries. |\n| `tests` | 3 — Cross-cutting | Tests the final refactored code, not intermediate states. |\n\n## Phases\n\nPhase order is strict — never start Phase N+1 before Phase N's checkpoint commit. Each phase builds on the prior phase's guarantees.\n\n### Phase 0: Safety Baseline (Lead Solo)\n\nEstablish that the codebase is in a known-good state before anyone touches it. Run tests, verify the build, confirm a clean working tree. Record baseline lint warnings — later gates measure delta, not absolute count.\n\nIf \"unused\" code may be dynamically selected (env vars, config, feature flags), flag it for the user before any agent deletes it.\n\n### Phase 1: Structural Surgery\n\nThese teammates change *what files exist*. Every other specialist needs a stable file structure. Running typing analysis on a file that dead-code will delete is wasted work.\n\nRun `dead-code` then `structure` sequentially — structure needs dead code removed first.\n\n**Critical:** File deletions and structural changes are high-risk. Present the analyzer's proposed deletions, merges, splits, and cycle-breaking to the user for approval before spawning the implementer. Only pass approved items.\n\nAfter implementation: run verification gates. Commit: `refactor(phase-1): structural surgery — [summary]`\n\n### Phase 2: Code Quality\n\nWith stable file structure, teammates improve code within files.\n\n**Batch ordering matters:**\n- **A — typing first.** Types constrain everything else.\n- **B — error-handling + correctness.** Depend on types but not each other. Parallel.\n- **C — duplication + perf.** Independent. Parallel alongside or after B.\n\nSpawn all applicable analyzer teammates in parallel. Wait for all reports. Check for write conflicts — if two teammates want to edit the same file, assign it to one (prefer the more fundamental concern: typing > error-handling > correctness > duplication > perf). Then spawn implementer teammates respecting batch order.\n\nAfter implementation: run verification gates. Commit: `refactor(phase-2): code quality — [summary]`\n\n### Phase 3: Cross-Cutting Concerns\n\nThese specialists need a global view across stable, quality-improved code. Skip if module-scoped and no cross-cutting issues surfaced.\n\nSpawn `patterns`, `security`, `tests` analyzer teammates in parallel. Serialize implementer changes that touch shared files.\n\nUnify toward the *dominant existing pattern* (>60% prevalence). Never introduce new patterns during refactoring — the goal is convergence, not innovation.\n\nAfter implementation: run verification gates. Commit: `refactor(phase-3): cross-cutting — [summary]`\n\n## Coordination Rules\n\n- **Analyze before implement.** Never spawn implementers until all analyzers in that phase finish. Review reports and resolve conflicts first.\n- **One writer per file.** Two teammates must never edit the same file concurrently. On conflict, assign to the teammate whose concern is more fundamental.\n- **Hard role separation.** Analyzers never edit. Implementers follow the report. The lead never writes production code.\n- **Preserve comments.** Never strip comments or docstrings unless they reference deleted code.\n\n## Verification Gates\n\nRun after every phase and after each batch. Each must pass before the next:\n\n1. **Typecheck** — 0 errors\n2. **Lint** — 0 new warnings vs baseline\n3. **Tests** — all pass\n4. **Build** — succeeds\n\nOn failure: up to 3 targeted fixes. If still failing, stop — summarize root cause, exact error, what was tried. Ask user.\n\n## Report\n\nWhen complete, summarize: phases run, teammates used, issues fixed/deferred, and gate results.","tags":["refactor","dotclaude","jhostalek","agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli","cursor"],"capabilities":["skill","source-jhostalek","skill-refactor","topic-agent-skills","topic-ai-coding","topic-anthropic","topic-claude","topic-claude-code","topic-claude-code-skills","topic-code-review","topic-codex-cli","topic-cursor","topic-developer-tools","topic-git-workflow","topic-multi-agent"],"categories":["dotclaude"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/JHostalek/dotclaude/refactor","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add JHostalek/dotclaude","source_repo":"https://github.com/JHostalek/dotclaude","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 (6,546 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:13:17.312Z","embedding":null,"createdAt":"2026-05-18T13:20:34.259Z","updatedAt":"2026-05-18T19:13:17.312Z","lastSeenAt":"2026-05-18T19:13:17.312Z","tsv":"'+1':448 '-1':617 '-2':137,721 '-3':798 '/.claude/skills/audit-':236 '/agents':223 '/skill.md':240 '0':465,894,898 '1':136,154,329,341,529,892 '2':159,622,896 '2a':354 '2b':369,380 '2c':391,397 '3':164,403,416,427,726,903,914 '4':907 '60':776 'absolut':504 'accur':373,384 'across':413,737 'activ':105 'agent':181,321,351,360,525 'agnost':246 'alongsid':662 'analysi':548 'analyz':65,195,208,278,314,337,586,669,759,805,813,851 'analyzer/implementer':255 'anyon':336,482 'append':312 'applic':668 'approv':600,607 'argument':24 'ask':6,929 'assign':690,839 'assum':91 'audit':233,424 'b':644,665 'baselin':134,152,467,496,902 'batch':634,711,885 'beyond':17 'boundari':425 'branch':97,112 'break':595 'brief':141 'build':457,489,908 'c':657 'caus':923 'chang':21,534,579,765 'check':677 'checkpoint':453 'claud':220 'clean':492 'cleanup':12 'code':42,85,328,339,409,422,435,508,555,564,571,623,631,722,742,863,875 'codebas':15,32,62,67,172,473 'comment':865,868 'commit':96,454,614,718,795 'complet':94,933 'concern':698,730,844 'concurr':836 'config':515 'confirm':490 'conflict':50,680,822,838 'constrain':357,641 'contain':186 'content':265 'context':68 'contract':389 'converg':787 'coordin':803 'correct':379,648,703 'count':505 'creat':107 'critic':574 'cross':167,405,418,429,728,751,800 'cross-cut':166,404,417,428,727,750,799 'cut':168,406,419,430,729,752,801 'cycl':594 'cycle-break':593 'dead':84,327,554,563,570 'dead-cod':83,326,553,562 'deep':14 'deleg':229 'delet':331,338,526,557,576,589,874 'delta':502 'depend':395,401,649 'depth':126 'dimens':75,81,133,151 'dir':222 'disciplin':256 'docstr':870 'domin':773 'duplic':390,658,704 'dynam':511 'e.g':80 'edit':204,290,686,832,853 'els':643 'enforc':54,254 'entir':61 'env':513 'error':367,377,646,701,895,925 'error-handl':366,645,700 'establish':45,470 'everi':538,880 'everyth':642 'exact':924 'execut':210,302 'exist':537,774 'fail':919 'failur':911 'featur':111,516 'file':71,262,291,332,344,349,536,544,551,575,627,633,689,769,827,835 'file-loc':348 'final':433 'find':201,286,316 'finish':334,346,817 'first':113,355,573,639,823 'fix':211,303,361,364,916 'fixed/deferred':940 'flag':517,518 'flow':121 'follow':855 'freelanc':213,310 'full':66,171,175 'fundament':697,847 'gate':56,500,613,717,794,877,942 'global':735 'goal':785 'good':479 'guarante':463 'guard':98 'handl':368,647,702 'hard':848 'high':582 'high-risk':581 'implement':205,293,300,604,610,708,714,764,791,807,810,854 'improv':16,630,741 'independ':392,398,660 'innov':789 'intermedi':437 'introduc':779 'issu':157,169,753,939 'item':608 'job':44 'judg':376 'known':478 'known-good':477 'later':499 'lead':29,468,859 'lighter':140 'line':251,298 'lint':497,897 'live':218 'local':20,216,350 'logic':365 'main/master':101 'match':124 'matter':636 'may':509 'md':224 'measur':501 'merg':590 'mode':194,245,250,272,279,294,297,301 'mode-agnost':244 'modul':131,146,149,414,746 'module-scop':145,745 'moves/splits/merges':343 'multipl':150 'must':115,333,345,830,887 'n':447,451 'name':78 'need':372,383,407,420,541,569,733 'never':203,212,444,778,808,831,852,860,866 'new':780,899 'next':891 'one':148,191,693,824 'orchestr':35 'order':318,325,394,400,441,635,712 'parallel':161,656,661,672,762 'pass':263,606,888,906 'path':23,59,63,74,378 'pattern':228,239,402,412,756,775,781 'per':826 'perf':226,238,396,659,705 'phase':86,90,93,153,158,163,174,322,439,440,446,450,456,461,464,528,616,621,720,725,797,816,881,935 'pipelin':125 'prefer':694 'prepend':249,271 'present':584 'preserv':864 'preval':777 'prior':92,460 'produc':199,284 'product':41,862 'prompt':188,261,270 'propos':588 'provid':64 'qualiti':55,624,723,740 'quality-improv':739 'rational':320 'read':197,259,282 'read-on':196,281 'receiv':206 'record':495 'refactor':1,10,22,33,60,70,114,215,434,615,719,783,796 'refactor-loc':214 'refer':873 'remov':572 'report':202,209,287,306,317,676,819,857,931 'resolv':49,821 'respect':710 'result':943 'resum':87 'revers':117 'review':818 'risk':583 'role':849 'root':922 'roster':177 'rule':804 'run':76,189,485,546,561,611,715,792,878,936 'safeti':46,466 'scale':118 'scope':57,128,147,274,280,747 'secur':415,757 'select':512 'self':185 'self-contain':184 'semant':388 'separ':850 'sequenc':47 'sequenti':567 'serial':763 'share':768 'skill':221,234,242 'skill-refactor' 'skip':162,743 'small':19,130 'solo':469 'source-jhostalek' 'spawn':135,258,602,666,707,755,809 'specialist':36,79,138,176,178,187,217,540,732 'split':591 'stabl':408,421,543,626,738 'standalon':232 'start':352,445 'state':438,480 'still':918 'stop':106,920 'strict':443 'strip':867 'structur':11,144,156,330,340,342,530,545,566,568,578,618,628 'substanti':9 'succeed':909 'summar':921,934 'summari':620,724,802 'surfac':170,754 'surgeri':531,619 'swap':295 'target':129,915 'team':28,143 'teammat':52,123,139,179,268,533,629,670,683,709,760,829,842,937 'test':426,431,486,758,904 'topic-agent-skills' 'topic-ai-coding' 'topic-anthropic' 'topic-claude' 'topic-claude-code' 'topic-claude-code-skills' 'topic-code-review' 'topic-codex-cli' 'topic-cursor' 'topic-developer-tools' 'topic-git-workflow' 'topic-multi-agent' 'touch':483,767 'toward':771 'tree':494 'tri':928 'two':193,682,828 'type':82,225,237,353,356,362,371,374,382,385,547,638,640,651,699 'typecheck':893 'unifi':411,770 'unless':165,871 'unus':507 'use':2,938 'user':5,522,598,930 'var':514 'verif':612,716,793,876 'verifi':387,487 'view':736 'vs':901 'wait':673 'want':684 'warn':498,900 'wast':559 'whose':843 'within':72,632 'work':48,120,493,560 'worktre':104,109 'write':40,679,861 'writer':825","prices":[{"id":"98ffdce0-69c4-46b8-b5d6-cbad3a26ff3e","listingId":"dffa842c-613a-4b45-9675-44becf8b141c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"JHostalek","category":"dotclaude","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:34.259Z"}],"sources":[{"listingId":"dffa842c-613a-4b45-9675-44becf8b141c","source":"github","sourceId":"JHostalek/dotclaude/refactor","sourceUrl":"https://github.com/JHostalek/dotclaude/tree/main/skills/refactor","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:34.259Z","lastSeenAt":"2026-05-18T19:13:17.312Z"}],"details":{"listingId":"dffa842c-613a-4b45-9675-44becf8b141c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JHostalek","slug":"refactor","github":{"repo":"JHostalek/dotclaude","stars":8,"topics":["agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli","cursor","developer-tools","git-workflow","multi-agent","prompt-engineering","skill-md"],"license":"cc0-1.0","html_url":"https://github.com/JHostalek/dotclaude","pushed_at":"2026-05-17T15:07:41Z","description":"Agent skills for agentic coding tools. Extremely opinionated. Updated (almost) daily.","skill_md_sha":"085d3ee359624046c9f61d7642c75591a7e353c7","skill_md_path":"skills/refactor/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JHostalek/dotclaude/tree/main/skills/refactor"},"layout":"multi","source":"github","category":"dotclaude","frontmatter":{"name":"refactor","description":"Use when the user asks for a substantial refactor, structural cleanup, or deep codebase improvement beyond a small localized change."},"skills_sh_url":"https://skills.sh/JHostalek/dotclaude/refactor"},"updatedAt":"2026-05-18T19:13:17.312Z"}}