working-with-legacy-code

name	working-with-legacy-code
description	Use when touching code without reliable automated tests or with nondeterminism such as time, randomness, or I/O.
metadata	{"short-description":"Working with legacy code safely"}

Purpose

Use this skill to change legacy code safely: code with weak tests, no tests, or behavior that is hard to make deterministic.

The goal is not to “make it perfect” immediately. The goal is to create safety, then change behavior in small steps. Rewrite is a last resort after characterization, seams, and small refactors are insufficient.

When to use

Invoke this skill before refactoring if any of the following is true:

• There are no reliable automated tests covering the behavior you will touch.
• Behavior depends on time, random, threads, network, filesystem, processes, or external services.
• Tests exist but are flaky, slow, or hard to run locally.

How to use

0. Open references/working-with-legacy-code.md. Pick the headings that match your situation and follow the order.

   • For language-specific example snippets, open one of:
     • references/working-with-legacy-code-cpp.md
     • references/working-with-legacy-code-py.md
     • references/working-with-legacy-code-ts.md

1. Create a safety net first:

   • Write a characterization test (current behavior) or a high-level regression test.
   • Make it deterministic using seams (dependency injection, wrappers, fakes).

2. Only after the safety net is green:

   • Extract small functions, isolate boundaries, and refactor in small diffs.
   • Keep build / format / static analysis / tests green at every step.

3. Treat rewrite as a last resort. If proposed, record why characterization + seams + small refactors are insufficient, which accumulated behaviors stay protected, and the rollback path.

4. If you cannot add a safety net, stop and explain why. Provide a reproducible manual procedure and the risk.

Output expectation

## Legacy Change Safety Record

- Touched behavior:
- Existing coverage:
- Safety-net test(s):
- Characterized current behavior:
- Preserved behavior / accumulated edge cases:
- Introduced seam(s):
- Refactor sequence:
- Intended behavior change:
- Rewrite avoided or justified:
- Verification commands/results: