Working with existing code

Most systems do not start at phase 1. Four workflows exist for code that already exists: recover the baseline, retrofit the tests, fix a bug, make a change. They write into the same workspace the forward phases use, so once a baseline is recovered the rest of the package works unchanged.

Recovering a baseline

ccw_start SDLC 0 Reverse Engineer

It begins with two deterministic scans — an inventory of the tree and the external surface (entry points, routes, handlers, clients) — and then reconstructs, in order: a system overview, the actors and domains, the behaviour (use cases from the external surface inward, the conceptual model from schema and ORM, business rules including every calculation, as-built requirements and evidenced NFRs) and the structure (the as-built solution architecture and a SUB-## decomposition mirroring the real module tree, with dependsOn taken from real imports).

Two rules make the output usable rather than plausible:

• Every record carries file/line evidence and a confidence level — observed, inferred or assumed — and the evidence is checked mechanically, not just claimed.
• Assumptions must be answered before sign-off. The run stops at an assumptions gate with everything marked assumed, you answer, and a strict re-verification runs before the baseline is documented. What you cannot answer stays recorded as an open question.

Out: a standard workspace — 00-reverse/ with the scans and findings, plus 01-requirements/, solution-architecture/ and 04-decomposition/ filled in exactly as phases 1, 2 and 4 would have written them, and the documentation site built over them.

Retrofitting a test suite

ccw_start SDLC Test Retrofit

Legacy code fails an absolute 95% gate on the first day and keeps failing, so this workflow uses a ratchet instead: never regress, and gain at least increment points per pass. Run it repeatedly; each run leaves the bar higher than it found it.

It adopts the project's own build and test tooling into manifests rather than restructuring anything, orders the work by risk — churn × size hotspots from git history — and then, per subsystem, writes characterization tests that pin current behaviour, bugs included. A test that encodes today's wrong answer is not a mistake here: it is the safety net. Where current behaviour contradicts the documented baseline, the difference is reported as a spec gap, not silently fixed.

A pass that stalls stops at a waiver gate. Out: retrofit-report.md and retrofit-findings.md in devDir, plus the coverage figures the next pass ratchets against.

Fixing a bug

ccw_start SDLC Bug Fix

The order is the point:

1. Record the report as BUG-### in 08-bugs/.
2. Reproduce it with a failing automated test, before any code changes. The reproduction is checked mechanically at system level. No reproduction, no fix — the workflow asks you for more information instead.
3. Triage. A true defect is fixed here. A report describing behaviour that matches the documented baseline, or asking for behaviour that was never specified, is a spec gap: the workflow routes it to SDLC 6 Change Request with a ready-to-paste request, rather than baking an undocumented decision into the code.
4. Fix the root cause and its siblings through SDLC Fix Subsystem — the same targeted path phase 5 uses, with its 95% branch gate and its diff-scoped review.
5. Verify that the reproducing test now passes, then optionally prove no regression with the full system suite.
6. Close BUG-###, and with hotfix: true, offer Release and Deploy straight away.

Making a change

ccw_start SDLC 6 Change Request

Takes projectName, workspaceDir, devDir and the change request verbatim.

This is the entry point for everything after the first build — not a re-run of phase 1. It assesses the change against the traceability chain (which use cases, requirements, subsystems and code it touches), records it as CH-### in 06-changes/, and stops at an impact gate with that assessment before anything is edited.

After you approve, it runs only the impacted phase workflows, in order: requirements, architecture, style guide, decomposition — each skipped when the impact analysis says it is untouched. It then refreshes the build map, rebuilds only the impacted subsystems, re-composes the app, and proves it with system tests plus the same bounded fix rounds phase 5 uses. Finally it closes the change record.

A change that turns out to touch nothing but one subsystem's code costs one rebuild. A change that moves a boundary re-runs decomposition first — and the documentation stays true either way, which is the whole reason to route changes through here.

Inspecting the built UI

ccw_start SDLC UI Inspection

Phase 5 runs this automatically for every subsystem that has an interface; start it directly to re-check one after a UI change.

It derives a capture plan — every screen × state × breakpoint — has the agent drive the browser tool the architecture chose, and captures screenshots plus computed DOM evidence. Then it gates deterministically on that evidence: no colours, fonts, sizes or spacings outside design-tokens.json; no breakpoint overflow; WCAG contrast on rendered text rather than on the palette; and a pixel diff against approved baselines. An agent review compares the screenshots to the UX spec, and accepting a new baseline is a human gate — because a visual change that is intended looks exactly like one that is not.