fabrico-reverse-engineering-spec

name

fabrico-reverse-engineering-spec

description

Reverse-engineer a complete, platform-agnostic SPEC.md from a running legacy web application by inspecting it with the Playwright MCP (Chrome automation): crawl routes, capture every screen, infer the data model, roles, flows, and integrations, then synthesize features into user stories with acceptance criteria. Use when modernizing an old web app to a newer stack or porting it to mobile/iOS. Produces a SPEC.md compatible with /fabrico-autopilot.

Reverse-engineering a spec from a running web app

Turn an existing (often legacy) web application into a clean, platform-agnostic SPEC.md that /fabrico-autopilot (or a migration build) can use to rebuild it on a modern stack or port it to mobile.

You observe the running app through the Playwright MCP (it drives a real Chromium/Chrome). You describe what the app does (behavior, data, roles, flows) — NOT how the old code is written. The output is a behavioral spec, not a code transliteration.

Inputs you need before starting

• Base URL of the running app (production, staging, or localhost).
• Access: if any area is behind login, the credentials or a logged-in session. Auth-gated areas you cannot reach must be flagged, not guessed.
• Scope: whole app, or specific areas/roles. If unspecified, cover everything reachable.

If the URL is missing or auth blocks a required area → STOP and ask the user (this is a true blocker).

Output artifacts

• SPEC.md — the deliverable, following the structure of SPEC.template.md, plus a Target (fill at build time) section (platform-agnostic) and a Source mapping appendix.
• legacy-inventory.md — sitemap/route inventory with per-screen notes.
• legacy-capture/ — screenshots and saved accessibility snapshots per screen (evidence).
• reverse-spec-notes.md — open questions, uncertainties, and assumptions for the user to confirm.

Process (track progress with this checklist)

Reverse-engineering progress:
- [ ] Step 1: Scope & access confirmed
- [ ] Step 2: Route/page inventory (sitemap)
- [ ] Step 3: Per-screen capture loop complete
- [ ] Step 4: Data model inferred
- [ ] Step 5: Roles, permissions & flows inferred
- [ ] Step 6: Integrations & non-functional inferred
- [ ] Step 7: Features synthesized into user stories with acceptance criteria
- [ ] Step 8: SPEC.md written + coverage gate passed

Step 1 — Scope & access

Confirm base URL, credentials, and scope. Open the app with the Playwright MCP and verify you can reach it. For the concrete browser recipe (which mcp__playwright__* tools to call and in what order), follow references/playwright-capture.md.

Step 2 — Route / page inventory

Crawl the app to build a sitemap: follow navigation, menus, links, and obvious URL patterns (e.g. /users, /users/:id/edit). Record every distinct screen/state in legacy-inventory.md. Note auth-gated areas and which role they belong to. Don't recurse infinitely — collapse list/detail pages into one representative example each.

Step 3 — Per-screen capture loop

For each screen in the inventory: take a screenshot, capture the accessibility-tree snapshot, and record the meaningful elements — forms (fields, types, validation hints, required markers), tables/lists (columns, filters, sorting, pagination), actions (buttons and what they do), navigation, and visible states (empty, error, loading, modals). Exercise key interactions (open a form, submit, paginate) to reveal behavior and validation. Save evidence under legacy-capture/.

Step 4 — Infer the data model

From forms, tables, detail pages, and URL patterns, infer the entities and their relationships (e.g. a "Users" table + "Edit user" form + /users/:id/orders ⇒ User 1—* Order). Capture fields, types, and obvious constraints. Express it as the lightweight entity sketch used in SPEC.template.md §5 — schemas are designed later by the architect.

Step 5 — Roles, permissions & flows

Compare what's visible/possible across roles (anonymous vs logged-in vs admin). Infer the role set and what each can do. Trace multi-step flows (e.g. checkout, onboarding, approval) end to end and document the steps.

Step 6 — Integrations & non-functional

From network requests and page content, identify external integrations (payment providers, maps, auth/SSO, analytics, email, third-party widgets) and note which are core vs incidental. Capture non-functional signals: languages/i18n, responsive behavior, auth model, file uploads, anything that affects a rebuild.

Step 7 — Synthesize features → user stories

Group screens/flows into epics and write concrete user stories with testable acceptance criteria (same shape as SPEC.template.md §4). Base every acceptance criterion on observed behavior; where behavior is unclear, write a provisional criterion and list the open question in reverse-spec-notes.md. Do NOT invent features the app doesn't have, and do NOT silently drop features you saw.

Step 8 — Write SPEC.md + coverage gate

Assemble SPEC.md using the SPEC.template.md structure, with two additions:

• A "Target (fill at build time)" section: keep the spec platform-agnostic; list candidate targets (modern web / iOS / React Native) and instruct that the concrete target is chosen by /fabrico-modernize or by editing this section before /fabrico-autopilot. UX described in behavioral terms (what the screen does), not pixel layouts, so it ports across platforms.
• A "Source mapping" appendix: table of old screen/URL → epic/story so nothing is lost and parity is checkable.

Coverage gate: every screen in legacy-inventory.md maps to at least one story (or is explicitly marked out-of-scope with a reason). If not, go back. Then summarize open questions from reverse-spec-notes.md for the user.

Important guidance

• Behavior over implementation. Describe what the app does for users and data, not the legacy framework's quirks.
• Don't guess behind auth. If you can't reach an area, flag it — never fabricate its features.
• Handle SPAs/dynamic content. Wait for content to load; interact to reveal hidden states (tabs, modals, lazy lists).
• Representative sampling for big lists. Document the pattern once; note volume rather than capturing every row.
• Mark every uncertainty. Anything inferred-but-unconfirmed goes to reverse-spec-notes.md with a clear question.
• Keep the spec platform-agnostic so the same SPEC.md can target modern web, iOS, or React Native.