surgeon

Name: surgeon
Author: Rune-kit

80stars21forks

How to install surgeon?

rune-kit/rune/surgeon

$npx -y skills add Rune-kit/rune --skill surgeon

Installs into the current project.

Summary

Incremental refactorer. Use when refactoring ONE module at a time within a rescue workflow after safeguard has set up safety nets — never as a standalone refactor for greenfield code. Applies proven patterns: Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract.

Files · 1

View on GitHub

SKILL.md

1	# surgeon
2
3	## Purpose
4
5	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.
6
7	<HARD-GATE>
8	- Blast radius MUST be checked before starting (max 5 files)
9	- Safeguard MUST have run before any edit is made
10	- Tests MUST pass after every single edit — never accumulate failing tests
11	- Never refactor two coupled modules in the same session
12	</HARD-GATE>
13
14	## Called By (inbound)
15
16	- `rescue` (L1): Phase 2-N SURGERY — one surgery session per module
17	- `improve-architecture` (L2): hand-off with proposal payload (depth/leverage/locality target + adapter list) — surgeon executes the deepening
18
19	## Calls (outbound)
20
21	- `scout` (L2): understand module dependencies, consumers, and blast radius
22	- `safeguard` (L2): if untested module found, build safety net first
23	- `improve-architecture` (L2): if no proposal payload provided, request one before refactoring
24	- `debug` (L2): when refactoring reveals hidden bugs
25	- `fix` (L2): apply refactoring changes
26	- `test` (L2): verify after each change (REPLACE old shallow-module tests with deepened-interface tests, don't layer)
27	- `review` (L2): quality check on refactored code
28	- `journal` (L3): update rescue progress
29
30	## Consuming proposal payloads
31
32	When invoked by `improve-architecture`, surgeon receives a proposal payload (YAML) containing:
33	- `module_path` — target
34	- `current` / `target` scores (depth/leverage/locality)
35	- `dependency_category` — informs test strategy
36	- `suggested_seam` — name of the deepened interface
37	- `adapters_planned` — at least 2 adapters means a real seam; surgeon implements all listed
38	- `tests_to_replace` — old shallow-module tests; DELETE in same commit as new tests land
39	- `tests_to_write_new` — at the deepened interface
40
41	Honor the payload. If the payload's `adapters_planned` lists only 1 adapter, push back — single-adapter seam is indirection.
42
43	## Execution Steps
44
45	### Step 1 — Pre-surgery scan
46
47	Call `rune:scout` targeting the module to refactor. Ask scout to return:
48	- All files the module imports (dependencies)
49	- All files that import the module (consumers)
50	- Total file count touched (blast radius check)
51
52	```
53	Count the unique files that would be modified in this surgery session.
54	If count > 5 → STOP. Split surgery into smaller sessions.
55	Report which files are in scope and which must wait for a later session.
56	```
57
58	Confirm that `rune:safeguard` has already run for this module (check for `tests/char/<module>.test.ts` and `rune-safeguard-<module>` git tag).
59
60	If safeguard has NOT run, call `rune:safeguard` now before continuing. Do not skip this.
61
62	### Step 2 — Select refactoring pattern
63
64	Based on module characteristics from scout, choose ONE pattern:
65
66	\| Pattern \| When to use \|
67	\|---\|---\|
68	\| Strangler Fig \| Module > 500 LOC with many consumers. New code grows alongside legacy, consumers migrate one by one. \|
69	\| Branch by Abstraction \| Tightly coupled module. Create interface → wrap legacy behind it → build new impl → flip the switch. \|
70	\| Expand-Migrate-Contract \| Changing a function signature or data shape. Expand (add new), migrate callers, contract (remove old). Each phase = one commit. \|
71	\| Extract & Simplify \| Specific function with cyclomatic complexity > 10. Extract sub-functions, simplify conditionals. \|
72
73	State the chosen pattern explicitly before starting.
74
75	### Step 3 — Refactor
76
77	Use `Edit` for all code changes. Rules:
78	- One logical change per `Edit` call — do not batch unrelated changes
79	- Changes MUST be small and reversible
80	- Never rewrite a file from scratch — use targeted edits
81	- Never change more than 5 files total in this session
82	- If a change reveals a hidden bug, stop and call `rune:debug` before continuing
83
84	Multi-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.
85
86	For Strangler Fig: Create the new module file first, then update one consumer at a time.
87
88	For **Branch

People who liked this also viewed

6 picks

Type

surgeon

80stars21forks

View on GitHub

How to install surgeon?

rune-kit/rune/surgeon

$npx -y skills add Rune-kit/rune --skill surgeon

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# surgeon
2
3	## Purpose
4
5	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.
6
7	<HARD-GATE>
8	- Blast radius MUST be checked before starting (max 5 files)
9	- Safeguard MUST have run before any edit is made
10	- Tests MUST pass after every single edit — never accumulate failing tests
11	- Never refactor two coupled modules in the same session
12	</HARD-GATE>
13
14	## Called By (inbound)
15
16	- `rescue` (L1): Phase 2-N SURGERY — one surgery session per module
17	- `improve-architecture` (L2): hand-off with proposal payload (depth/leverage/locality target + adapter list) — surgeon executes the deepening
18
19	## Calls (outbound)
20
21	- `scout` (L2): understand module dependencies, consumers, and blast radius
22	- `safeguard` (L2): if untested module found, build safety net first
23	- `improve-architecture` (L2): if no proposal payload provided, request one before refactoring
24	- `debug` (L2): when refactoring reveals hidden bugs
25	- `fix` (L2): apply refactoring changes
26	- `test` (L2): verify after each change (REPLACE old shallow-module tests with deepened-interface tests, don't layer)
27	- `review` (L2): quality check on refactored code
28	- `journal` (L3): update rescue progress
29
30	## Consuming proposal payloads
31
32	When invoked by `improve-architecture`, surgeon receives a proposal payload (YAML) containing:
33	- `module_path` — target
34	- `current` / `target` scores (depth/leverage/locality)
35	- `dependency_category` — informs test strategy
36	- `suggested_seam` — name of the deepened interface
37	- `adapters_planned` — at least 2 adapters means a real seam; surgeon implements all listed
38	- `tests_to_replace` — old shallow-module tests; DELETE in same commit as new tests land
39	- `tests_to_write_new` — at the deepened interface
40
41	Honor the payload. If the payload's `adapters_planned` lists only 1 adapter, push back — single-adapter seam is indirection.
42
43	## Execution Steps
44
45	### Step 1 — Pre-surgery scan
46
47	Call `rune:scout` targeting the module to refactor. Ask scout to return:
48	- All files the module imports (dependencies)
49	- All files that import the module (consumers)
50	- Total file count touched (blast radius check)
51
52	```
53	Count the unique files that would be modified in this surgery session.
54	If count > 5 → STOP. Split surgery into smaller sessions.
55	Report which files are in scope and which must wait for a later session.
56	```
57
58	Confirm that `rune:safeguard` has already run for this module (check for `tests/char/<module>.test.ts` and `rune-safeguard-<module>` git tag).
59
60	If safeguard has NOT run, call `rune:safeguard` now before continuing. Do not skip this.
61
62	### Step 2 — Select refactoring pattern
63
64	Based on module characteristics from scout, choose ONE pattern:
65
66	\| Pattern \| When to use \|
67	\|---\|---\|
68	\| Strangler Fig \| Module > 500 LOC with many consumers. New code grows alongside legacy, consumers migrate one by one. \|
69	\| Branch by Abstraction \| Tightly coupled module. Create interface → wrap legacy behind it → build new impl → flip the switch. \|
70	\| Expand-Migrate-Contract \| Changing a function signature or data shape. Expand (add new), migrate callers, contract (remove old). Each phase = one commit. \|
71	\| Extract & Simplify \| Specific function with cyclomatic complexity > 10. Extract sub-functions, simplify conditionals. \|
72
73	State the chosen pattern explicitly before starting.
74
75	### Step 3 — Refactor
76
77	Use `Edit` for all code changes. Rules:
78	- One logical change per `Edit` call — do not batch unrelated changes
79	- Changes MUST be small and reversible
80	- Never rewrite a file from scratch — use targeted edits
81	- Never change more than 5 files total in this session
82	- If a change reveals a hidden bug, stop and call `rune:debug` before continuing
83
84	Multi-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.
85
86	For Strangler Fig: Create the new module file first, then update one consumer at a time.
87
88	For **Branch

People who liked this also viewed

6 picks

Type