Brownfield Retrospective

Run ECC's engineering process retroactively against a project that was built without it. Pick any slice of an existing codebase, audit what exists, reconstruct how it got there, extract a four-axis gap register, then execute the fixes forward through the standard ECC pipeline.

The workflow is slice-first: no whole-repo onboarding is required before it is useful, and every phase is re-enterable from a durable artifact on disk. Start in the middle, work backwards, then move forward.

When to Activate

• Adopting ECC in a repository that already exists and is already shaped
• User asks to "audit my existing project", "retro this codebase", or "what did we miss?"
• Taking over, inheriting, or returning to a codebase after a long gap
• User asks "why is it like this?" followed by "should it stay like this?"
• A module, feature, or service needs a rethink before the next feature lands on top of it
• Deciding whether a legacy area should be fixed forward, rewritten, or left documented as-is

When Not to Use

• Greenfield work with no existing code — use planner and tdd-workflow directly
• Onboarding to spec-driven development without the redesign loop — the spec-miner agent does that on its own
• A launch go/no-go production-readiness pass — use production-audit
• Security-only sweeps — use security-review
• Team process retrospectives (sprint ceremonies) — this audits a codebase, not people

The Working Set

All artifacts are written inside the audited project, under docs/retro/<slice>/:

Backfilled decisions go to docs/adr/ per the architecture-decision-records skill. If the project uses OpenSpec, reconstructed-spec.md may instead be openspec/specs/<capability>/spec.md produced by spec-miner.

How It Works

Phase 0 — Pick the Entry Point

Start from what the user cares about today. Do not map the whole repo first.

Any of these is a valid slice:

Record the perimeter at the top of gap-register.md before anything else: paths in scope, entry points, callers, blast radius. Budget the slice at roughly 15 files or 2,000 lines; if the user's pick is bigger, cut it into named sub-slices and register each as its own row of work. A slice too big to audit in one session is a slice that never finishes. Keep a Current phase: marker beside the perimeter and advance it each time a phase completes.

Phase 1 — Present-State Audit

Establish what exists now, with evidence. Do not fix anything yet.

1. Recon the slice: manifest and framework fingerprint, entry points, test layout, CI checks (borrow the recon steps from codebase-onboarding, scoped to the perimeter).
2. Run the reviewers that match the stack, in parallel where possible. Every finding must carry a file:line pointer:
   • The language reviewer for the stack (typescript-reviewer, python-reviewer, go-reviewer, ...)
   • security-reviewer
   • silent-failure-hunter for swallowed errors
   • type-design-analyzer where invariants are encoded in types
   • performance-optimizer only if the slice is on a hot path
3. Snapshot the current state: test count and coverage, lint/CI status, TODO/FIXME/HACK inventory inside the perimeter.

Write everything to baseline-audit.md. Findings that get fixed during this phase corrupt the baseline — hold them for the register.

Phase 2 — Backward Reconstruction

Work backwards from the present state to the decisions that produced it.

…