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

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

1. 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

1. 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.
2. 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 reconstruction into register rows. One axis per class of gap:

Register format (the table is the skill's durable output):

| ID | Axis | Gap | Evidence | Forward fix | Severity | Effort | Status |
|----|------|-----|----------|-------------|----------|--------|--------|
| G-001 | practice | Errors swallowed in retry loop | src/api/retry.ts:42 | Propagate + map at boundary | P1 | S | open |

• Severity: P0 security exposure or data loss, P1 correctness, P2 practice and observability, P3 selection and cleanup.
• Effort: S under a session, M a few sessions, L needs its own plan.
• Status: open, in-progress, done, wont-fix.
• Every row needs an evidence pointer. A gap you cannot point at is an opinion.

Phase 4 — Redesign / Rethink

Turn the register into a sequenced plan. Follow the project's existing task and approval authority. Keep the register as audit evidence linked to that system; do not create competing canonical task state. Confirm scope and obtain project-required approval before a rewrite, technology replacement, migration, or other material change.

1. Run architect or code-architect over the P0 and P1 rows to produce target-design.md: target shape for the slice, the fix sequence, and an explicit "what does not change" list to protect working behavior.
2. Backfill retro-ADRs for every undocumented decision from Phase 2. Mark them as reconstructed (status: proposed (reconstructed), date of the retro, note the original decision predates the record). Separate observed history from inferred intent, and have the project owner confirm a decision before marking it accepted. Never present a backfilled ADR as if it were written at decision time.
3. Triage every register row into one of: fix-forward (repair in place), rewrite (replace the slice), leave-documented (wont-fix). A wont-fix must record its reason in the register — a wont-fix with a reason closes the thinking gap; a silent one reopens it.
4. Sequence the backlog: P0 first, then interleave quick wins with larger repairs to keep momentum.

Phase 5 — Forward Execution

Work the register through the standard ECC pipeline, one row per session as a baseline pace:

planner (scope the row)
  → tdd-guide (failing test first — for a legacy gap the first test
    usually encodes the missing invariant from reconstructed-spec.md)
  → implement
  → code-reviewer
  → security-reviewer (if the row touches input, auth, or data)
  → doc-updater + ADR (if the decision changed)
  → conventional commit
  → mark the register row done

• Update gap-register.md statuses as rows close; the register is the durable state, not the conversation.
• On session boundaries, hand off through the project's memory mechanism (unified-memory, context carriers) so the next session resumes from the register alone.

Phase 6 — Closure and Re-Audit

When every row is done or wont-fix:

1. Re-run the Phase 1 audit over the same perimeter.
2. Diff against baseline-audit.md and verify with verification-loop — the gaps claimed closed must stay closed.
3. Record the delta (findings then, findings now, rows closed, rows deferred) at the bottom of gap-register.md.
4. Anything that resurfaced becomes a new row, not a failure — the register is a loop, not a one-shot.

Resuming Mid-Stream

Any session can start in the middle. Read docs/retro/<slice>/gap-register.md first:

• Register exists with a row in-progress → Phase 5, finish that row.
• Register exists with at least one row, all rows closed → Phase 6.
• Register exists, rows open, none in progress → resume at the Current phase: marker (Phase 3 register awaiting triage, or Phase 4 backlog awaiting its first row).
• No register, but baseline-audit.md exists → Phase 2.
• No artifacts at all → Phase 0 with the user.

Anti-Patterns

• Auditing the whole repo before any slice — the workflow is slice-first by design.
• Fixing code during Phases 1-3 — audit phases produce the register; edits mid-audit corrupt the baseline.
• Register rows without evidence pointers.
• wont-fix without a recorded reason.
• Presenting backfilled ADRs as contemporaneous records.
• Skipping the Phase 6 re-audit — closure is verified, not declared.

Related Skills

• codebase-onboarding — recon baseline for Phase 1
• architecture-decision-records — retro-ADR backfill in Phase 4
• tdd-workflow — Phase 5 execution discipline
• verification-loop — Phase 6 closure
• production-audit — launch-readiness lens (complementary, later)
• security-review — security-only requests