| name | fabrico-reverse-engineering-spec |
| description | Build a platform-agnostic `SPEC.md` from an authorized running app with Playwright. |
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 bundled
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 Playwright MCP operations to use 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 the bundled
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 the bundled 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 bundled
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.
