From rune
Refactors one module per session using Strangler Fig, Branch by Abstraction, and Expand-Migrate-Contract patterns. Use post-safeguard in rescue workflows for safe, tested changes.
npx claudepluginhub rune-kit/rune --plugin @rune/analyticsThis skill uses the workspace's default tool permissions.
Incremental refactorer that operates on ONE module per session using proven refactoring patterns. Surgeon is precise and safe — it applies small, tested changes with strict blast radius limits. Each surgery session ends with working, tested code committed.
Orchestrates multi-session refactoring of legacy/messy codebases: autopsy assessment, safety nets, incremental module surgery, progress tracking. Use for 'refactor' or old code cleanup.
Guides refactoring code structure and modules to improve maintainability, readability, and performance while preserving external behavior and ensuring all tests pass.
Share bugs, ideas, or general feedback.
Incremental refactorer that operates on ONE module per session using proven refactoring patterns. Surgeon is precise and safe — it applies small, tested changes with strict blast radius limits. Each surgery session ends with working, tested code committed.
- Blast radius MUST be checked before starting (max 5 files) - Safeguard MUST have run before any edit is made - Tests MUST pass after every single edit — never accumulate failing tests - Never refactor two coupled modules in the same sessionrescue (L1): Phase 2-N SURGERY — one surgery session per moduleimprove-architecture (L2): hand-off with proposal payload (depth/leverage/locality target + adapter list) — surgeon executes the deepeningscout (L2): understand module dependencies, consumers, and blast radiussafeguard (L2): if untested module found, build safety net firstimprove-architecture (L2): if no proposal payload provided, request one before refactoringdebug (L2): when refactoring reveals hidden bugsfix (L2): apply refactoring changestest (L2): verify after each change (REPLACE old shallow-module tests with deepened-interface tests, don't layer)review (L2): quality check on refactored codejournal (L3): update rescue progressWhen invoked by improve-architecture, surgeon receives a proposal payload (YAML) containing:
module_path — targetcurrent / target scores (depth/leverage/locality)dependency_category — informs test strategysuggested_seam — name of the deepened interfaceadapters_planned — at least 2 adapters means a real seam; surgeon implements all listedtests_to_replace — old shallow-module tests; DELETE in same commit as new tests landtests_to_write_new — at the deepened interfaceHonor the payload. If the payload's adapters_planned lists only 1 adapter, push back — single-adapter seam is indirection.
Call rune:scout targeting the module to refactor. Ask scout to return:
Count the unique files that would be modified in this surgery session.
If count > 5 → STOP. Split surgery into smaller sessions.
Report which files are in scope and which must wait for a later session.
Confirm that rune:safeguard has already run for this module (check for tests/char/<module>.test.ts and rune-safeguard-<module> git tag).
If safeguard has NOT run, call rune:safeguard now before continuing. Do not skip this.
Based on module characteristics from scout, choose ONE pattern:
| Pattern | When to use |
|---|---|
| Strangler Fig | Module > 500 LOC with many consumers. New code grows alongside legacy, consumers migrate one by one. |
| Branch by Abstraction | Tightly coupled module. Create interface → wrap legacy behind it → build new impl → flip the switch. |
| Expand-Migrate-Contract | Changing a function signature or data shape. Expand (add new), migrate callers, contract (remove old). Each phase = one commit. |
| Extract & Simplify | Specific function with cyclomatic complexity > 10. Extract sub-functions, simplify conditionals. |
State the chosen pattern explicitly before starting.
Use Edit for all code changes. Rules:
Edit call — do not batch unrelated changesrune:debug before continuingMulti-layer refactors: when the deepening or extraction touches 2+ layers within the module (e.g., types + logic + interface), decompose into vertical-slice tracer-bullet edits rather than horizontal layer passes. Each slice = one end-to-end edit chain that produces a verifiable outcome (one Edit per layer, immediately tested). See plan/references/vertical-slice.md for slice rules and granularity. Horizontal "all-types-then-all-logic-then-all-interface" passes are forbidden inside surgeon — they break the "test after each Edit" discipline (Step 4) by leaving intermediate states untestable.
For Strangler Fig: Create the new module file first, then update one consumer at a time.
For Branch by Abstraction: Create the interface first (commit), wrap legacy (commit), build new impl (commit), switch (commit). Four commits minimum.
For Expand-Migrate-Contract: Expand (add new API alongside old), migrate each caller (one commit per caller if possible), contract (remove old API last).
For Extract & Simplify: Extract sub-functions one at a time. Each extraction = one commit.
After every Edit, call rune:test targeting:
tests/char/<module>.test.tsIf any test fails → STOP. Do NOT continue with more edits.
Call rune:debug to investigate. Fix before next edit.
The code MUST stay in a working state after every single change.
After all edits for this session are complete and tests pass, call rune:review on the changed files.
Address any CRITICAL or HIGH issues raised by review before committing.
Use Bash to commit this surgery step:
git add <changed files>
git commit -m "refactor(<module>): [pattern] — [what was done]"
The commit message MUST describe which pattern was used and what changed. Each commit must leave the codebase in a fully working state.
Call rune:journal to record:
STRANGLER FIG — New code grows around legacy (module > 500 LOC, many consumers)
BRANCH BY ABSTRACTION — Interface → wrap legacy → build new → switch
EXPAND-MIGRATE-CONTRACT — Each step is one safe commit
EXTRACT & SIMPLIFY — For complex functions (cyclomatic > 10)
- NEVER refactor 2 coupled modules in same session
- ALWAYS run tests after each change
- Max blast radius: 5 files per session
- If context low → STOP, save state, commit partial work
- Each commit must leave code in working state
- Never skip safeguard, even for "simple" changes
## Surgery Report: [Module Name]
- **Pattern**: [chosen pattern]
- **Status**: complete | partial (safe stopping point reached)
- **Health**: [before] → [after estimated]
- **Files Changed**: [list, max 5]
- **Commits**: [count]
### Steps Taken
1. [step] — [result] — [test status]
### Remaining (if partial)
- [what's left for next surgery session]
- Recommended: re-run rune:surgeon targeting [module] — session 2
### Next Step
[if complete]: Run rune:autopsy to update health scores
[if partial]: Commit this checkpoint, then start new surgeon session for remaining work
Known failure modes for this skill. Check these before declaring done.
| Failure Mode | Severity | Mitigation |
|---|---|---|
| Editing without confirming safeguard ran first | CRITICAL | HARD-GATE: check for tests/char/<module>.test.* AND rune-safeguard-<module> tag before first edit |
| Exceeding 5-file blast radius without splitting | HIGH | HARD-GATE: count files in scope before starting — stop and split if > 5 |
| Batching multiple edits before running tests | HIGH | HARD-GATE: run tests after every single Edit call — never accumulate untested changes |
| Wrong pattern chosen for module size/type | MEDIUM | Match pattern explicitly: Strangler Fig = large/many-consumers, Extract = high cyclomatic complexity |
| Not committing at safe stopping points when context runs low | MEDIUM | Every commit = working state — stop before context limit, not after losing partial work |
refactor(<module>): <pattern> — <description>| Artifact | Format | Location |
|---|---|---|
| Refactored module | Edited source files (max 5) | in-place |
| Before/after diff | Git diff | via git diff |
| Surgery Report | Markdown | inline |
| Git commit(s) | Conventional commits | git history |
| Journal entry | Text | via journal L3 |
~3000-6000 tokens input, ~1000-2000 tokens output. Sonnet. One module per session.
Scope guardrail: surgeon operates on ONE module per session (max 5 files). Any work beyond that scope must be deferred to a separate surgeon session.