Brownfield Discovery

Brownfield Discovery

Overview

Build Like Amazon's canonical flow assumes a greenfield path: /wb → /design → /spec → /build. Most real adoption happens on existing projects with code, IaC, CI/CD, observability, and on-call already running — but no BLA artifacts.

This skill closes that gap. It does an engineering reverse pass on the project: reads the code, IaC, CI, dashboards, and external dependency calls, then produces a Design Document, API contracts, and a Threat Model anchored in the real state of the system. Subsequent /spec and /build invocations use these reverse-engineered artifacts as their anchor — exactly as they would use canonical artifacts in greenfield.

This is not retroactive approval. The output carries a banner saying "REVERSE-ENGINEERED — not approved by any bar raiser, used as context, not as historical decision record." It exists so the agent stops re-discovering the project on every invocation and so future bar raisers have something to compare against.

When to Use

• The project already exists (significant code, IaC, CI present) and there are no BLA artifacts (docs/design/, docs/working-backwards/)
• The user asks for a medium or large change in such a project (small / trivial changes don't need this — they go through the proportionality ladder directly)
• The user explicitly invokes /onboard
• Periodically, when the project drifts significantly from the prior reverse-engineered baseline (architecture change, major refactor)

Do NOT use for:

• Greenfield projects (use /wb → /design instead)
• Projects that already have a canonical Design Doc (use that as the anchor)
• Trivial or small changes (the ladder in using-amazon-skills/SKILL.md handles those without needing discovery)
• "Just to have docs" — discovery is a means to anchor future changes, not documentation for documentation's sake

Amazon Context

Inside Amazon, services accumulate years of decisions that live only in the heads of long-tenured engineers and in the code. New owners onboarding a service do a structured system walkthrough — a disciplined pass where they read the code, the runbooks, the incident history, and produce a written summary of the system as it is. This skill is the same pattern: a one-time, structured pass that produces written artifacts so the next reader (human or agent) is not starting from scratch.

The artifacts produced are deliberately marked as reverse-engineered. Pretending a reverse-engineered Design Doc is the same as one approved by a Design Bar Raiser would corrupt the process — bar raisers exist precisely because retroactive justification is not the same as upfront design.

The Process

brownfield-discovery runs in one of three paths, picked by the user via AskUserQuestion at the start. The differences:

The agent presents these three as outcome-framed options (not process names) and runs the chosen path. The shared engine (Steps 1–6 below) is the same; Path B and C extend Path A with additional steps.

Step 0: Pick the path

Use AskUserQuestion to surface the three options to the user, framed by outcome:

Detected: existing project, no BLA artifacts. How would you like to use /onboard?

[A] Anchor only — produce a Design Doc, API contracts, and a Threat Model from the existing code. Future /spec and /build use these as anchor. Does not try to recover the customer story or PR/FAQ. Recommended for "I'll keep building here, give me the agent the context it needs." ~15–30min.

[B] Validate the why — everything in [A], plus an inferred PR/FAQ reconstructed from the code, README, and docs. The doc-bar-raiser persona surfaces hard questions where the code can't tell us why. Recommended for "I built fast and want to check whether I'm solving the right problem." ~30–45min.

[C] Forward WB + Gap Analysis — full /wb from scratch (5 stages with approval gates) as if this were greenfield, with the agent reading the existing code during the conversation. At the end, produces a gap-analysis.md comparing "what we'd build today" vs "what exists." Recommended for "I'm pivoting / re-strategizing / want to revalidate from scratch." ~1–2h.

If the user does not answer or asks the agent to pick, default to A.

Steps 1–6 — Shared engine (run in all 3 paths)

These steps form Path A in full. Path B and Path C extend them with additional steps below.

1. Inventory pass (read-only, ~5–10min)

Read the project in breadth, not depth. Goal: a bird's-eye view.

• Languages, frameworks, runtime versions — package.json, pyproject.toml, go.mod, pom.xml, Cargo.toml, etc.
• Entrypoints — handlers, main, Lambda function entries, controllers, queue consumers, scheduled jobs
• IaC — CloudFormation templates, CDK code, Terraform, Pulumi, Kubernetes manifests
• CI/CD — .github/workflows, .gitlab-ci.yml, buildspec.yml, Jenkinsfile, pipeline configs
• Observability — structured logging libraries, metrics emission, alarms / dashboards declared in IaC, OpenTelemetry instrumentation
• External dependencies — HTTP clients, SDK clients (DynamoDB, S3, etc.), queue producers/consumers, database connections
• Tests — unit / integration / e2e coverage; testing frameworks
• Config — environment variables, parameter store, config files; what's externalized vs hardcoded
• Auth / security boundaries — middleware, IAM roles, API keys, JWT verification, encryption usage
• Data stores — schemas, migrations, ownership

Produce a brief inventory list. Don't write prose yet.

2. Architecture inference (~5–10min)

From the inventory, infer:

• High-level architecture — components, data flows (read path / write path), sync vs async boundaries. Express as a Mermaid diagram.
• Existing API surface(s) — what does this service expose? REST endpoints (route table → OpenAPI), gRPC services (.proto files or inferred from code), event topics/queues (publishers, subscribers, payload shapes), CLI commands, MCP tools, etc.
• Patterns present (or absent) — single-instance? Multi-AZ? Multi-region? Cell-based? Bulkhead isolation? Control-plane / data-plane split? Static stability? Event-driven with outbox? Saga? Cross-reference patterns/INDEX.md and assess whether each is present, partial, or absent.
• Trust boundaries — where untrusted input enters; how it's validated; what crosses an authentication/authorization boundary.

For each inference, note your confidence level (high / medium / low) and the evidence that supports it (file paths, line ranges, IaC resources). Inferences with low confidence are flagged for the user.

3. Reverse-engineer the Design Document

Produce docs/design/<service-name>/design-doc.md using the canonical template (skills/design-document/templates/design-doc-template.md), with these adjustments:

• Banner at top — must say:

  ⚠️ REVERSE-ENGINEERED — produced by brownfield-discovery from the existing codebase on <date>. Not approved by any bar raiser. Use as context for future changes, not as a historical record of decisions made. Sections marked LOW CONFIDENCE were inferred without strong evidence and should be reviewed.

• Per-section confidence: each section ends with a confidence line: [Confidence: HIGH / MEDIUM / LOW] and one sentence on what supports the rating.

• Section 1 (Problem Statement) — likely LOW in Path A: the customer problem rarely lives in the code. Pull what you can from the README, docstrings, marketing pages if present; otherwise mark explicitly as "TO BE FILLED — customer context not inferable from code." (In Path B and C, this section is filled more completely — see Steps 7+ below.)

• Section 2 (Requirements) — MEDIUM to HIGH for non-functional requirements that show up in code (latency targets in alarms, throughput in autoscaling configs, error budgets in dashboards). Functional requirements: MEDIUM at best — list the observable behaviors the API exposes.

• Section 3 (Proposed Architecture) — HIGH confidence: this is the strongest part of reverse-engineering. Diagrams, components, data flows, storage choices.

• Section 4 (Alternatives Considered) — NOT INFERABLE. Mark as: "Not reverse-engineered — alternatives considered at original design time are not recoverable from code. Future changes should re-evaluate alternatives in context."

• Section 5 (Trade-offs) — MEDIUM: infer from architecture choices made (e.g., "this service uses DynamoDB; the implied trade-off is key-value over ad-hoc query, accepting that analytical queries require a separate path"). Flag inferred trade-offs explicitly.

• Section 6 (Cost Estimation) — MEDIUM if billing data accessible; otherwise estimate from infrastructure footprint (instance counts, storage GB, request volume from metrics). Mark assumptions.

• Section 7 (Operational Concerns) — HIGH: existing alarms, dashboards, runbooks (if present) are observable directly. List them as-is. Gaps (no alarm for X) are findings, not failures.

• Section 8 (Testing Strategy) — HIGH: what tests exist; what's missing.

The Design Doc is not pristine — it carries the project's existing debt visibly. Don't paper over gaps; surface them.

4. Reverse-engineer the API Contracts

For each API surface identified in step 2, produce the canonical contract artifact (per skills/api-contract-first/SKILL.md mapping):

• REST: if openapi.yaml exists, link it; if not, generate one from route definitions in code (Express/Fastify routes, FastAPI decorators, Spring @RequestMapping, etc.). Save to docs/design/<service>/openapi.yaml.
• gRPC: link existing .proto files; if missing (rare), reconstruct from generated stubs.
• GraphQL: link existing schema; if absent (rare), inspect resolvers.
• Events / async: produce an asyncapi.yaml describing channels (queues / topics) and operations (publish / subscribe), plus payload schemas (JSON Schema / Avro / Protobuf) inferred from event producers' code.
• MCP tools: read tool definitions if exposed.
• CLI / SDK: list commands, flags, exit codes; output schemas.

Each artifact carries a header comment: # REVERSE-ENGINEERED from <source files>. Confidence: HIGH/MEDIUM/LOW. Review before relying on this for client integration.

5. Reverse-engineer the Threat Model

Produce docs/design/<service>/threat-model.md:

• Trust boundaries observed — where untrusted input enters; auth/authz checkpoints; encryption boundaries.
• Existing controls — auth middleware, input validation, encryption at rest / in transit, secrets management (where), audit logging.
• Obvious gaps — missing input validation on a public endpoint, secrets in environment variables without rotation, logs that may contain PII, unauthenticated internal endpoints.
• STRIDE quick pass — for each major component, list which STRIDE categories have observable mitigations and which don't.

This is not a complete threat model — it's a starting baseline. Mark as such.

6. Pattern catalog cross-reference

For each pattern in patterns/*/PATTERN.md, note: present, partial, or absent in the current architecture. This goes into a section of the Design Doc and into a separate patterns-observed.md, becoming input for future /design invocations that scan the pattern catalog.

Don't recommend pattern changes here — that's a future /design decision. Only document what's there.

Path A only — close out

After steps 1–6, present the closing summary via AskUserQuestion:

Path A complete. Produced in docs/design/<service>/:

• design-doc.md — confidence: HIGH on architecture/operations, LOW on customer problem and alternatives
• API contracts — confidence HIGH (one artifact per protocol used)
• threat-model.md — baseline only
• patterns-observed.md

[A] Accept as starting context (recommended) [B] Review LOW-confidence sections together [C] Discard

If [A]: save artifacts; brief end-of-onboarding summary; done. If [B]: walk through LOW-confidence sections; prompt for input; update. If [C]: delete or move to docs/design/_discarded/.

Skip Steps 7+ if Path A was chosen.

Path B — Reverse Working Backwards (extends 1–6)

7. Reverse-engineer the WB artifacts (~10–20min)

Produce inferred WB artifacts in docs/working-backwards/<service-name>/. Each artifact carries the same banner as the Design Doc — REVERSE-ENGINEERED, INFERRED, with per-section confidence.

Sources for inference:

• README, top-level project docs, comments
• API endpoint names and shapes (suggests intended capabilities)
• UI labels, error messages, copy that's visible to end users (suggests audience)
• Documentation in docs/, especially anything that looks like requirements or design discussion
• Test names (often describe customer-visible behaviors)
• Issue tracker / commit messages (when present)

Produce these files (DRAFT, INFERRED):

• customer-profile.md — who appears to be the customer based on the artifacts. Confidence will usually be LOW: inferring "who" from code is unreliable.
• problem-statement.md — what problem the project appears to solve. Pull from README + docs; do not fabricate.
• solution-sketch.md — the existing system, described in the language of "what this lets the customer do." Higher confidence — derived from API + UI surface.
• prfaq.md — DRAFT press release + FAQ, with each FAQ answer either filled (from inferable content) or marked TO BE FILLED — needs customer evidence.

Mark every section that depends on customer evidence as INFERRED — needs validation. Never fabricate. The customer story is the part that the code cannot answer.

8. Doc Bar Raiser pass (mandatory in Path B)

Activate the doc-bar-raiser persona (agents/doc-bar-raiser.md) in "Inferred PR/FAQ review" mode. The persona's job here is not to bless the PR/FAQ — it's to surface the questions the user has to answer themselves by talking to real customers / sponsors / stakeholders.

Produce docs/working-backwards/<service-name>/bar-raiser-questions.md with the structured questions, grouped by section (customer, problem, solution, business case, metrics).

9. Path B closing gate

Present via AskUserQuestion:

Path B complete. Produced everything from Path A, plus inferred WB artifacts in docs/working-backwards/<service>/.

Notably: the doc-bar-raiser surfaced N questions where the code cannot tell us why. Strongly recommend you answer them before continuing.

[A] Accept as starting context. I'll keep the bar-raiser questions visible for future invocations. [B] Walk through the bar-raiser questions with me now. [C] Discard the WB artifacts (keep Path A's design artifacts).

Path C — Forward WB + Gap Analysis (full /wb run, then compare)

Path C is the heaviest path. It is intended for strategic re-evaluation — pivots, major refactors, "we lost our way" moments. It runs the canonical Working Backwards flow with full approval gates, knowing the existing project, and produces a gap analysis at the end.

7'. Run Working Backwards from scratch (full /wb flow)

Hand off to the canonical working-backwards skill (skills/working-backwards/SKILL.md). Run all 5 stages with their mandatory approval gates:

• Listen → Define → Invent → Refine → Test

Critical: during this WB run, the agent has read access to the existing project. Use it to:

• Acknowledge what already exists when the user proposes a solution ("you already have X — does the customer profile we just defined still match?")
• Push back when the WB the user is constructing diverges from what's been built ("you said the customer is A, but the existing system mostly serves B — which is right?")

Equally critical: do not let the existing project bias the WB. The whole point of Path C is to re-derive from the customer outwards. If the WB says "build Y" and Y already exists, that's a useful confirmation. If WB says "build Z" and the system actually does W, that's a strategic gap — record it.

The WB artifacts go to docs/working-backwards/<service>/ as canonical (no INFERRED banner — they were produced through the real WB process with the user).

8'. Gap Analysis (~10–20min)

After WB approval, produce docs/design/<service>/gap-analysis.md:

• Capabilities in the new WB — what the PR/FAQ says the product enables for the customer
• Capabilities in the existing system — derived from the Design Doc produced in Steps 1–6
• Gaps:
  • In WB but not built — capabilities the customer should have per the new WB but the project does not deliver
  • Built but not in WB — capabilities that exist but don't map to anything in the new WB (candidates for sunset / refactor / re-justification)
  • Built but materially different — capabilities present in both, but with implementation that diverges from what the new WB envisions
• Recommendations: for each gap, classify as extend (add to project) / sunset (remove from project) / re-justify (keep but document why) / align (refactor toward the WB target).

The recommendations are suggestions for future /design invocations — Path C does not implement them.

9'. Path C closing gate

Present via AskUserQuestion:

Path C complete. Produced:

• Full canonical WB artifacts in docs/working-backwards/<service>/
• Reverse-engineered design artifacts in docs/design/<service>/ (from steps 1–6)
• gap-analysis.md cross-referencing them

[A] Accept all. Future /spec and /build use the design artifacts as anchor; the gap-analysis informs the next /design. [B] Walk through the gap-analysis with me to prioritize next moves. [C] Discard all and go back to default.

Mechanisms Over Good Intentions

Common Rationalizations

Red Flags

• 🚩 Reverse-engineered Design Doc has no confidence ratings — the agent hid its uncertainty.
• 🚩 "Customer Problem" section is filled in with confidence HIGH — the agent inferred a customer story from code, which is rarely possible.
• 🚩 "Alternatives Considered" is filled in — alternatives at original design time are not recoverable from code; the agent fabricated them.
• 🚩 Threat Model is presented as complete — it's a baseline, not a full threat model.
• 🚩 Discovery was run on a trivial project where no future medium/large change is planned — wasted effort.
• 🚩 The user accepted the discovery output without reviewing low-confidence sections, then later relied on those sections as if they were canonical.

Verification

Path A (always)

• User explicitly chose a path (A / B / C) via Step 0 — choice is logged in the output summary
• Inventory pass produced a concrete list of languages, IaC, CI, observability, deps, data stores, auth boundaries
• Architecture inference produced a Mermaid diagram with confidence ratings on each component
• docs/design/<service>/design-doc.md exists with the REVERSE-ENGINEERED banner and per-section confidence
• At least one API contract artifact exists per identified API surface, with the standard appropriate to the protocol (OpenAPI / .proto / AsyncAPI / etc.)
• Threat model baseline exists with trust boundaries, existing controls, obvious gaps
• Pattern catalog cross-reference exists in the Design Doc and as a separate patterns-observed.md
• Subsequent /spec and /design invocations are aware of these artifacts (they appear in repo state detection)

Path B (in addition to A)

• WB artifacts exist in docs/working-backwards/<service>/ with REVERSE-ENGINEERED, INFERRED banner and per-section confidence
• No customer story / problem / metric was fabricated — sections that depend on customer evidence are marked INFERRED — needs validation
• bar-raiser-questions.md exists with structured hard questions from the doc-bar-raiser

Path C (in addition to A)

• Full canonical WB artifacts produced through the canonical working-backwards skill, with all 5 approval gates honored — these do not carry the INFERRED banner because they came from the user, not from inference
• gap-analysis.md exists with capabilities-in-WB / capabilities-built / gaps grouped as extend / sunset / re-justify / align

Tenets

1. Discovery is investment, not documentation. It exists to anchor future changes, not to look professional.
2. Confidence ratings are non-negotiable. Never claim certainty about what was inferred without strong evidence.
3. The customer story rarely lives in code. Don't fabricate it. In Path B, surface the questions; do not invent the answers.
4. Reverse-engineered ≠ approved. The banner is mandatory on inferred artifacts. Bar raisers exist precisely because retroactive justification is not the same as upfront design. Path C produces canonical WB artifacts because they go through the canonical WB process with the user — those don't carry the INFERRED banner.
5. Run once, reuse always. If the project drifts significantly later, re-run discovery — but in steady state, the artifacts persist and serve every subsequent /spec and /build.
6. Surface debt; don't paper over it. Gaps in observability, missing tests, missing controls — list them as findings. Reverse-engineering is also auditing.
7. The user picks the path; the agent does not assume. A new project may need only Path A. A pivot needs Path C. The choice belongs to the user, with outcome-framed options.