Skip to main content
Agent skill

Brownfield Retrospective

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.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Brownfield Retrospective when an AI agent needs a reusable SKILL.md workflow for this job: 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.

When not to use it

Skip Brownfield Retrospective when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/brownfield-retrospective
# Save SKILL.md to ~/.claude/skills/brownfield-retrospective/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/brownfield-retrospective/SKILL.md. For a shared project, commit the folder at .claude/skills/brownfield-retrospective/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Brownfield Retrospective skill for this task: Use Brownfield Retrospective when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

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

| Axis | Question | Sources | |------|-----------|---------| | Thinking | What was decided but never recorded? Which invariants live only in code? | Decision inventory, reconstructed spec | | Coding practice | Where does the code diverge from how ECC would have written it? | Phase 1 findings, the `rules/` pack for the language, spec items with no test anchor | | Missing features | What would a day-one build have included that this slice never got? | Boundary input validation, observability, rate limiting, idempotency, migrations plus rollback, a11y, i18n, user docs, CI gates | | Technology selection | Is the chosen tech fighting the codebase? Outdated, duplicated, risky, or missing? | Dependency inventory, git archaeology, recon |

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

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

```text 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

Intended uses

  • Use Brownfield Retrospective when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.