arsdlc-brownfield

Rewrite is the most expensive word in software. The gateway into an old system is: baseline, characterize, seam, then change by delta only.

Step 0: Facts first, then questions

Everything in the baseline that a command can answer, you answer: stack, build/test commands (run them, record exit codes), churn, TODO density, dependency age, test coverage if a report exists. Only the pain points, the must-never-change list and the risk appetite are questions for the human; ask them with arsdlc-grill in one round, each with a recommended answer drawn from what you read. Add every legacy term you had to decode to docs/glossary.md.

Step 1: Baseline (read-only, 15 minutes max)

Produce docs/features/<slug>/baseline.md:

• Stack & entrypoints: languages, frameworks, build & test commands that actually work today (run them, record exit codes with npx arsdlc evidence <slug> -- <command>).
• Hotspots: count file appearances from git log --format= --name-only with the available shell's grouping tools; report the top 10 plus TODO/FIXME density.
• Pain points from the user, verbatim.
• Must-never-change list: public APIs, data formats, schedules, integrations. Each becomes a golden-master candidate.
• Unknowns: things you could not determine. Never guess; list them as [NEEDS CLARIFICATION] so arsdlc-spec blocks until resolved.

Step 2: Characterization tests (golden masters)

For each must-never-change item, write a test that pins current behaviour, even if that behaviour looks wrong. The purpose is detection, not judgement.

• Prefer snapshot/approval style at the boundary (HTTP response, CLI output, file output, DB row shape).
• Record the first green run as evidence: npx arsdlc evidence <slug> -- <test command>.
• Add a spec requirement per golden master: WHILE the migration is in progress THE SYSTEM SHALL preserve <behaviour>.

Step 3: Seams (choose the laziest safe one)

Name the places where new behaviour can be introduced without editing the old path:

• Strangler-fig facade (route new calls, leave old ones).
• Branch by abstraction (interface + old impl + new impl + toggle).
• Expand/contract for schema changes (add, dual-write, migrate, remove).

Write them into plan.md under ## Seams, each with the toggle or flag that controls it. Prefer the seam that touches the fewest legacy files and needs the fewest new abstractions (ponytail ladder: reuse an existing interface before inventing one). A characterization test at the seam is mandatory before the seam is opened.

Step 4: Hand off

• Discovery continues in arsdlc-discover with the baseline attached.
• Every change from here on is a delta against the baseline (arsdlc-delta). If you find yourself editing an untested legacy path, stop and add a characterization test first.

Smells to refuse

• "It's easier to rewrite." Until the baseline exists and the golden masters run, that sentence is an opinion with no evidence behind it. It is also the single most expensive sentence in software.
• A baseline assembled from the README. Stack, entrypoints and test commands come from running them and recording exit codes. A baseline that was never executed is fiction with a file extension.
• Characterization tests that judge. They pin what the system does, including the parts that look wrong. If you "fix" the behaviour while writing the test, you have written a spec test, not a golden master, and it will not detect anything.
• A seam opened before its characterization test is green. Order is baseline → characterize → seam → change. Skipping a step means the seam's regression signal is missing exactly when you need it.
• A must-never-change list with no test attached. An item on the list with no golden master is a wish. Attach one or move it to Unknowns.
• Guessing at Unknowns. An unexamined legacy behaviour written down as a fact will be quoted back to you for the rest of the feature. Leave the marker.