/brownfield-retrospective

name: brownfield-retrospective
description: Run the ECC engineering process retroactively against an existing project slice. Audit current state, reconstruct past decisions, produce a four-axis gap register (thinking, coding practice, missing features, technology selection), then execute fixes forward through the plan-TDD-review pipeline. Use when adopting ECC mid-project, taking over an inherited codebase, or asking what was missed and what would have been built differently from day one.
metadata:
  origin: ECC

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>/`:

| File | Phase | Purpose | |------|-------|---------| | `gap-register.md` | 0-6 | The state machine — perimeter, `Current phase:` marker, and rows. The only file required to resume mid-stream. | | `baseline-audit.md` | 1 | Reviewer findings, test/CI snapshot, TODO inventory. | | `reconstructed-spec.md` | 2 | What the code actually does today (Requirements + Invariants). | | `target-design.md` | 4 | Target shape for the slice and the fix sequence. |

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:

| User signal | Slice | |-------------|-------| | Names a directory, module, or service | That path plus its direct callers | | Names a feature or user flow | The files that implement it, traced from the entry point | | Names a bug, incident, or pain point | The code that produced it plus one level of call chain | | Names a dependency or tech choice | Everything that touches it | | Names nothing | The 2-3 hottest paths by churn — propose them and let the user pick |

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.

1. Mine the behavioral spec: run `spec-miner` against the slice. Its Requirements (WHEN → THEN) and Invariants become `reconstructed-spec.md` — the baseline truth for Phase 5 tests. 2. Git archaeology on the perimeter:

• `git log --oneline -- <slice>` for directory history; use `--follow` only with a single file path — age, authors, cadence
• Largest and most reverted commits — where the design changed under pressure
• Churn hotspots — files changed far more often than neighbors
• Dead ends — branches or scaffolding that never shipped

3. Decision inventory: list the significant decisions frozen into the code (stack and framework choices, data model, boundaries, error strategy, state management). Check each against `docs/adr/`, README, and comments. Every decision with no written record is itself a pre-existing thinking gap — record it in Phase 3, do not silently backfill it here. 4. Where behavior is opaque, use `code-explorer` to trace execution paths before guessing at intent.

Phase 3 — Gap Analysis (Four Axes)

Convert the audit and reconstru