Reconstruct an Existing App

You have an application that already exists — working code, maybe some screenshots, maybe a README — but no single document that describes how it is structured. Discussing this app with AI agents means re-explaining the same context over and over. Reconstructing a spec solves this: you get a compact, structured description that any agent can read immediately.

When This Applies

• You have a codebase but no up-to-date documentation of the interface structure.
• You want to discuss the app with AI agents without pasting hundreds of files into context.
• You are planning a redesign or refactor and need a clear picture of what exists today.
• You want to onboard a new AI agent (or a new team member) quickly.

What You Reconstruct

The goal is a UI Spec that captures the current state of the application: which screens exist, what blocks are on each screen, what each block does. Optionally, a Data Spec that captures entities, fields, and relationships.

This is not about inventing new features. It is about making the existing app visible as a structured document.

The Workflow

1. Gather your sources

Collect what you have. Any combination works:

• Code — components, pages, routes, layouts.
• Screenshots — actual screens of the running app.
• README or docs — any existing documentation, even if outdated.
• Your own knowledge — you know how the app works, even if it is not written down.

You do not need all of these. Even one source is enough to start.

2. Give it to an AI agent with the format

Paste the UI Spec Format into a chat with an AI agent, along with your sources. Ask the agent to reconstruct a UI Spec from what you provided.

How you frame it depends on what you have:

• From code: "Here are the main page components of my app. Reconstruct a UI Spec from them."
• From screenshots: "Here are screenshots of my application. Reconstruct a UI Spec describing each screen and its blocks."
• From description: "I'll describe my app screen by screen. Create a UI Spec from my description."
• Mixed: "Here is the README, a few screenshots, and some key components. Reconstruct a UI Spec."

The agent returns a structured spec — screens, blocks, purposes — based on what it can infer from your sources.

3. Import into Spec Canvas

Create a new project in Spec Canvas and import the generated UI Spec. Browse the screens and blocks. Check whether the agent captured the structure correctly:

• Are all screens present?
• Do the block purposes match what the screens actually do?
• Is anything missing or misunderstood?

4. Fix and refine

The first reconstruction is rarely perfect. Some blocks may be too vague, some screens may be missing, some purposes may not match the real behavior. Update the spec — either manually in the editor or by asking the agent to adjust specific parts.

If you want to verify visually, generate HTML implementations for key screens and compare them against the real app. This makes gaps and inaccuracies obvious.

5. Optionally add a Data Spec

If you want the reconstruction to cover the data layer, give the agent the Data Spec Format along with your database schema, ORM models, or API types. The agent reconstructs entities, fields, relationships, and enums.

Having both specs gives you a complete map of the application — interface and data model — in two compact files.

What You Get

• A structured description of your existing app that fits in a single file.
• A document that any AI agent can read to understand the app without scanning the codebase.
• A starting point for redesign, refactoring, or feature planning — you know exactly what exists before deciding what to change.
• A shared reference for conversations with AI agents — instead of "look at the code in /src/pages/dashboard," you say "look at the dashboard screen in the spec."

Tips

• Start with the screens you work on most. You do not need to reconstruct the entire app at once. Start with the core screens and expand later.
• Screenshots work surprisingly well. AI agents can infer screen structure, block layout, and even some behavior from screenshots alone. If your code is messy but the UI is clear, screenshots may be the easiest source.
• Do not aim for perfection. The first spec is a rough map, not a blueprint. It becomes more accurate as you use it and refine it over time.
• Use the spec as your correction anchor. Once the spec exists, point agents to it instead of re-explaining the app. See Spec as Verification Layer.
• Combine with Rethink UX. Once you have a spec of the existing app, you can immediately start exploring how to improve it. See Rethink UX.

Related

• Prepare Handoff to AI — how to use the reconstructed spec for coding.
• Rethink UX — how to explore improvements once you have a spec.
• Patterns & Practices — progressive precision, spec diff, verification layer.