Rescue

rescue

Purpose

Legacy refactoring orchestrator for safely modernizing messy codebases. Rescue runs a multi-session workflow: assess damage (autopsy), build safety nets (safeguard), perform incremental surgery (surgeon), and track progress (journal). Designed to handle the chaos of real-world legacy code without breaking everything.

• Surgery MUST NOT begin until safety net is committed and tagged.
• ONE module per session. NEVER refactor two coupled modules simultaneously.
• Full test suite must pass before rescue is declared complete.

Triggers

• /rune rescue — manual invocation on legacy project
• Auto-trigger: when autopsy health score 5:

→ STOP surgery on this module → Report: "Blast radius [N] files exceeds limit of 5 — use Strangler Fig pattern to reduce scope first" → Pick a smaller sub-module to start with

**Sb. Execute surgery.**

REQUIRED SUB-SKILL: rune:surgeon → Invoke surgeon with:

• module: [module name and path]
• pattern: [recommended_pattern from autopsy]
• blastradiusfiles: [list from pre-surgery check]
• dependency_report: [from Phase 0]
• characterization_tests: [paths from Phase 1]

Supported patterns: Strangler Fig — for modules > 500 LOC: route traffic to new impl gradually Branch by Abstraction — for replacing implementations: introduce interface first Expand-Migrate-Contract — for safe transitions: expand API, migrate callers, contract old API Extract & Simplify — for cyclomatic complexity > 10: extract pure functions

surgeon returns: modified files list, refactoring summary, test results.

**Sc. Review surgery output.**

REQUIRED SUB-SKILL: rune:review → Invoke review with: modified files, surgeon summary. → review checks: code quality, pattern adherence, no regressions introduced. → Capture: review verdict (pass | fail | warnings).

If review verdict == fail: → STOP, do not commit → Report review findings to user → Revert surgeon changes: Bash: git checkout [modified-files]

**Sd. Run characterization tests.**

Bash: [project test command, e.g. npm test or pytest] If tests fail: → STOP immediately → Report: "Characterization tests broken by surgery on [module] — reverting" → Bash: git checkout [modified-files] → Do NOT mark todo complete → Update RESCUE-STATE.md with failure note

**Se. Commit and save state.**

Bash: git add [modified-files] Bash: git commit -m "refactor([module]): [pattern] — [brief description]"

REQUIRED SUB-SKILL: rune:journal → Update RESCUE-STATE.md:

• module [name]: status=complete, healthbefore=[X], healthafter=[Y]
• sessions_used: [increment]

REQUIRED SUB-SKILL: rune:session-bridge → Save updated state for next session resume.

**Context check — before continuing to next module:**

If approaching context limit (50+ tool calls or user signals fatigue): → STOP after current module commit → Report: "Session limit reached. Rescue state saved. Resume with /rune rescue to continue." → Do NOT start next module in same session

Mark SURGERY todo `completed`.

Repeat for each module in queue across subsequent sessions.

---

### Phase N+1 — CLEANUP

Mark CLEANUP todo `in_progress`.

Run only after ALL surgery todos are `completed`.

**Remove boundary markers.**

Grep: find all @legacy, @bridge markers in codebase Bash: grep -rn "@legacy\|@bridge" --include=".ts" --include=".js" -l

For each file with markers: → Remove @legacy blocks (old implementation replaced) → Remove @bridge shims (migration complete) → Keep @new-v2 comments only if they add documentation value; otherwise remove Edit each file to strip markers.

**Verify markers removed.**

Bash: grep -rn "@legacy\|@bridge" --include=".ts" --include=".js" Expected: no output. If any remain → fix before continuing.

Bash: git add -A && git commit -m "chore: rescue cleanup — remove @legacy and @bridge markers"

Mark CLEANUP todo `completed`.

---

### Phase N+2 — VERIFY

Mark VERIFY todo `in_progress`.

Bash: [full test command] Capture: passed, failed, coverage %.

If tests fail: → Do NOT mark rescue complete → Identify which module introduced failure → Report: "Final verify failed: [failing test list]"

REQUIRED SUB-SKILL: rune:autopsy → Invoke autopsy again with scope: "full". → Capture: healthscorefinal.

**Compare health scores.**

healthscorebaseline: [from Phase 0 RESCUE-STATE.md] healthscorefinal: [from this autopsy] improvement: [final - baseline]

Report: Rescue complete. Health: [baseline] → [final] (+[improvement] points) Modules refactored: [count] Sessions used: [count]

REQUIRED SUB-SKILL: rune:journal → Final RESCUE-STATE.md update: status=complete, health_final=[score].

Bash: git tag rune-rescue-complete

Call `neural-memory` (Capture Mode) to save refactoring patterns and decisions from this rescue.

Mark VERIFY todo `completed`.

---

## Status Command

`/rune rescue status` — reads RESCUE-STATE.md via `journal` and presents:

Rescue Dashboard

• Health Score: [before] → [current] (target: [goal])
• Modules: [completed]/[total]
• Current Phase: [phase]
• Sessions Used: [count]

Module Status

| Module | Status | Health | Pattern | |--------|--------|--------|---------| | auth | done | 72→91 | Strangler Fig | | payments | in-progress | 34→?? | Extract & Simplify | | legacy-api | pending | 28 | TBD |

---

## Safety Rules

NEVER refactor 2 coupled modules in same session ALWAYS run characterization tests after each surgery Max blast radius: 5 files per session If context low → STOP, save state via journal + session-bridge, commit partial Rollback point: git tag rune-rescue-baseline (set in Phase 0)

## Constraints

1. MUST run autopsy diagnostic BEFORE planning any refactoring — understand before changing
2. MUST create safety net (characterization tests via safeguard) BEFORE any code surgery
3. MUST NOT refactor two coupled modules simultaneously — one module per session
4. MUST run full test suite after EVERY individual edit — never accumulate failing tests
5. MUST tag a safe rollback point before starting surgery
6. MUST NOT exceed blast radius of 5 files per surgical session

## Mesh Gates

| Gate | Requires | If Missing |
|------|----------|------------|
| Autopsy Gate | autopsy report with health score before planning | Run rune:autopsy first |
| Safety Gate | safeguard characterization tests passing before surgery | Run rune:safeguard first |
| Surgery Gate | Each edit verified individually (tests pass) | Revert last edit, fix, re-verify |

## Output Format

Rescue Report: [Module Name]

• Status: complete | partial | blocked
• Modules Refactored: [count]
• Tests Before: [count] ([pass rate]%)
• Tests After: [count] ([pass rate]%)
• Health Score: [before] → [after]
• Rollback Tag: [git tag name]

## Returns

| Artifact | Format | Location |
|----------|--------|----------|
| Rescue state | Markdown | `RESCUE-STATE.md` (updated each session) |
| Characterization tests | Source files | Written by `rune:safeguard` per module |
| Refactored modules | Source files | Modified in-place, committed per surgery session |
| Health score comparison | Inline (Rescue Report) | Baseline vs final autopsy scores |
| Rescue Report | Markdown (inline) | Emitted at session end (per module and final) |

## Document Ownership

| Scope | Access | Files |
|-------|--------|-------|
| **Owns** (read + write) | `RESCUE-STATE.md`, `.rune/rescue-*.md`, git tags (`rune-rescue-*`), refactored source files (one module per session) |
| **Reads** (never writes) | `CLAUDE.md`, autopsy reports, safeguard test files, `.rune/contract.md` |
| **Never modifies** | Test files written by `safeguard` (characterization tests are the safety net — rescue reads them, never edits), `compiler/**`, `SKILL.md` files |

Rescue delegates to `surgeon` for actual code changes and `safeguard` for test creation. Rescue owns the orchestration state, not the artifacts.

## Anti-Patterns

Common legacy refactoring failures. These turn "rescue" into "make it worse."

| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| **Big bang refactor** — rewriting everything at once | No rollback path. One bug = entire refactor is broken | One module per session. Commit + verify after each module |
| **Surgery without safety net** — refactoring before characterization tests exist | No way to verify behavior is preserved. "It compiles" ≠ "it works" | HARD-GATE: safeguard tests must pass BEFORE any surgery begins |
| **Coupled module surgery** — refactoring two interdependent modules simultaneously | Changes in module A break module B mid-surgery. Neither is stable | One module per session. Stabilize A completely before touching B |
| **Ignoring the autopsy** — starting refactoring without understanding current health | Fixes symptoms not causes. Wastes effort on low-impact modules | Phase 0 autopsy is mandatory. Surgery queue ordered by impact, not convenience |
| **Prototype patterns in production** — replacing legacy code with quick-and-dirty rewrites | Creates new legacy. The "rescue" becomes the next rescue target | Apply proven refactoring patterns from autopsy recommendations. Clean code, not fast code |
| **No rollback point** — surgery without a tagged baseline | If surgery goes wrong, no safe state to return to | `git tag rune-rescue-baseline` before ANY code changes |

## Sharp Edges

Known failure modes for this skill. Check these before declaring done.

| Failure Mode | Severity | Mitigation |
|---|---|---|
| Starting surgery before safety net committed and tagged | CRITICAL | HARD-GATE: `rune-rescue-safety-net` git tag must exist before Phase 2 |
| Refactoring two coupled modules in the same session | HIGH | HARD-GATE: one module per session — split coupled modules into sequential sessions |
| Blast radius > 5 files before surgery halted | HIGH | Count importers before each surgery — stop if > 5 and split scope |
| Not saving state between sessions (rescue spans many sessions) | MEDIUM | journal + session-bridge mandatory after each session — RESCUE-STATE.md must be current |
| Continuing surgery after characterization tests fail on current code | MEDIUM | Tests must PASS on unmodified code first — fix the test if current behavior is captured wrongly |

## Done When

- autopsy complete with quantified health score and surgery queue
- safeguard characterization tests passing on current code (HARD-GATE)
- All modules in surgery queue processed (one per session)
- @legacy and @bridge markers removed from codebase (CLEANUP phase)
- Final autopsy run — health_score_final > health_score_baseline
- Rescue Report emitted with before/after health comparison and session count

## Cost Profile

~$0.10-0.30 per session. Sonnet for surgery, opus for autopsy. Multi-session workflow.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Rune-kit](https://github.com/Rune-kit)
- **Source:** [Rune-kit/rune](https://github.com/Rune-kit/rune)
- **License:** MIT

Install and usage instructions live in the source repository linked above.