Characterize

Pin what the code does today — not what it should do — so you can change it without silently breaking it. From Michael Feathers, Working Effectively with Legacy Code: a characterization test documents existing behavior; you write it, THEN change the code, and the test tells you if you altered behavior you didn't mean to.

This is the inverse of tdd-loop:

The loop

1. Find a seam. Identify where you can observe the code's output without changing it — a pure function's return, an HTTP handler's response, a CLI's stdout, a rendered DOM. If there's no seam, introduce the minimum one (extract a function, inject a dependency) — that itself is a behavior-preserving refactor; do it tiny and commit separately.
2. Capture current output (the golden master). Run the code against representative inputs (include real production-shaped data + edge cases from the hotspots list). Record exactly what it returns/emits — bugs included. You are documenting reality, not correctness.
3. Write the test asserting that captured output. Name it so the gate recognizes it: <name>.characterization.test.<ext> (JS/TS) or test_<name>_characterization.py (Python), co-located or under the repo's test root. Use the repo's existing test runner (see AGENTS.md / atlas).
4. Run it — it must PASS immediately (it asserts what the code already does). A failing characterization test means your captured oracle is wrong; fix the capture, not the code.
5. Record the ledger. Write verify/<date>/<task>/green.log (it passed) so the TDD-ledger gate is satisfied. There is no red.log requirement for characterization — note "characterization (no prior test)" in the task instead.
6. Now you may change the code. Make your change; re-run the characterization test. If it fails, you changed observable behavior — decide deliberately: update the golden master (with a one-line rationale) or revert.
7. Remove the path from the manifest. Once a flagged-legacy file has a characterization test, delete its glob (or the file) from .claude/state/adopt/uncharacterized-paths.txt so autopilot and verify.sh stop blocking it.

For NEW features in untested legacy: sprout, don't touch

If the task ADDS behavior (not modifies), use Feathers' Sprout Method/Class: write the new logic in a fresh, fully-TDD'd function/class and call it from the legacy code with the smallest possible edit. The legacy body stays untouched — so you never owe it a characterization test, and the new code gets normal tdd-loop red→green rigor.

Hard rules

• Characterize before you change. No tests = no writes (verify.sh enforces; SKIP_CHAR_GATE=1 is a human-only override, never an autopilot one).
• Document reality, including bugs. If the legacy code returns the wrong total, the characterization test asserts the wrong total. Fixing the bug is a separate, later task with its own spec — now made safe because the test will flag the behavior change.
• Smallest seam. Don't refactor broadly to make code testable; introduce the minimum seam, commit it alone, then characterize.
• Hotspots first. Characterize the churn×LOC hotspots from ADOPTION-REPORT.md before the long tail — that's where factory-driven change is most likely and most dangerous.

References

• Michael Feathers, Working Effectively with Legacy Code (characterization tests, seams, sprout/wrap)
• docs/research/brownfield-onboarding.md (the adoption research brief)
• .claude/skills/tdd-loop/SKILL.md (the greenfield counterpart)
• .claude/commands/adopt.md (Phase 4 invokes this)