Inspect Spec — Written by Humans

Goal

Thoroughly inspect a target web product and produce a complete build spec (build-spec.md) and feature list (prd.json) that another AI agent can use to build a working clone from scratch.

Assumptions

The user is ALREADY LOGGED IN to the target product in the browser.
An Ever CLI session is ALREADY running. Do NOT run ever start.
You have full access to all authenticated pages and features.
You should actively USE the product, not just read pages passively.
A .env file exists in the project directory with API keys for the target product. Read it to get credentials for testing API features directly (e.g., sending test requests via curl).

Out of Scope — DO NOT include these in the PRD

Paywalls, billing, subscription management
Any payment processing

Authentication — MUST include in the PRD

Login, signup, OAuth, magic links, email verification, and password reset are in scope and must be inspected and added as P1 PRD entries. See Phase A.2 in inspect-prompt.md for the full auth inspection strategy.

SDK / Language Scope

If the target product offers SDKs or code examples in multiple languages (Python, Ruby, Go, etc.), ONLY include TypeScript/Node.js in the PRD. Ignore all other language SDKs.

For the clone:

Build the web dashboard UI only
If the product has an API, clone it as a Node.js/TypeScript API
If the product shows code snippets to users, only show TypeScript/Node.js examples
Skip any language-specific SDK pages during inspection

Inspection Strategy

Phase A: Read pre-scraped docs (FAST — already on disk)

Docs are NOT your job to scrape. A deterministic Python scraper (scripts/scrape-docs.py, driven by Scrapling + trafilatura) ran before iteration 1 and populated target-docs/. Your job in this phase is to consume what's there, not to fetch anything from the network.

What's on disk:

target-docs/
├── INDEX.md          # List of every scraped page with a one-line description
├── coverage.json     # Discovery method used + page count + status
├── full-docs.md      # (optional) Single-file dump from llms-full.txt
├── openapi.json|.yaml  # (optional) API contract if the target exposes one
├── overview.md
├── api-reference/...
├── guides/...
└── ...mirrors the target's docs URL hierarchy

Steps:

cat target-docs/INDEX.md — get the table of contents.
cat target-docs/coverage.json — confirm coverage (page_count, discovery, passed: true).
If target-docs/openapi.json or target-docs/openapi.yaml exists, read it. This is the authoritative API contract — generate API-related PRD entries directly from it instead of guessing from prose.
Read the docs files you need. Each one has a `` comment at the top so you can cross-reference back to the live page if you need to inspect the rendered version with Ever CLI.

Do NOT:

Run curl https://r.jina.ai/...
Run curl <site>/llms.txt or curl <site>/sitemap.xml
Use ever navigate <docs-url> && ever extract to read docs pages

The scraper already tried all of these. Doing them again wastes an iteration and you'll get the same result.

If target-docs/INDEX.md is missing or coverage.json shows passed: false: the scraper failed. STOP and surface the failure in inspect-progress.txt. Do not try to scrape docs by hand — fix the scraper instead (.venv-scrape/bin/python scripts/scrape-docs.py <url> --force).

This phase should take ≤ 1 iteration. Read the index, skim what matters for the DX summary, then move on to UI testing.

Phase A.1: Onboarding Flow Discovery (during docs phase)

The logged-in user has likely ALREADY COMPLETED the target product's onboarding, so the onboarding UI (setup wizards, first-run guides, empty states) won't be visible during inspection. You MUST discover the onboarding flow from docs.

Why this matters: Onboarding is a core product feature, not an auth flow. The clone needs its own onboarding experience so new users know what to do after signing up.

Step 1: Search the scraped docs Look through target-docs/ for onboarding-related content:

Quickstart / getting-started guides
Setup wizards or first-run flows
"Welcome" or "getting started" pages
Empty state descriptions (what users see before they have data)

Step 2: Use the docs search bar or AI assistant (if available) Many docs sites have a search bar or AI assistant (e.g., Mintlify's assistant, GitBook's search). If the docs don't have a dedicated onboarding page, use these to ask:

"What is the onboarding process?"
"What steps does a new user complete after signing up?"
"What does the first-run experience look like?"

Use Ever CLI to interact with the search/assistant:

bash

ever snapshot   # Find the search bar or assistant button
ever click <search-element>
ever type "onboarding process"

# Read the results / assistant response

ever snapshot
ever extract

Save the assistant's response to target-docs/onboarding-flow.md.

Step 3: Document the onboarding flow Create target-docs/onboarding-flow.md (if not already created from Step 2) with:

The step-by-step onboarding sequence
What data/config the user provides at each step
What the product looks like BEFORE the user has set anything up (empty states)
Any skippable vs. required steps
What "done" looks like (when does the user land on the main dashboard?)

Step 4: Add onboarding PRD entries Add PRD entries for each onboarding step with category "onboarding", priority P2-P3 (right after core infra/API). These should include:

The onboarding wizard/flow UI
Empty states for core features (what users see before they have data)
Any first-run guided tours or tooltips

Iteration 1: Site Map

ever snapshot the main dashboard to see all navigation links.
Map the COMPLETE site structure and save it to sitemap.md:

- Every page in the navigation (sidebar, top nav, footer) - Sub-pages and tabs within each page - URLs for each page - Page type: list view, detail view, form, settings, etc.

Record the overall layout pattern (sidebar + content, top nav + pages, etc.).
Record the tech stack if detectable (check page source, network requests).
Take a screenshot of the main dashboard: ever screenshot --output ralph/screenshots/home.jpg

Iterations 2-N: Feature-by-Feature Deep Dive (USE Ever CLI to test UI)

For each page/feature (one per iteration):

Navigate to the page.
ever snapshot to see all interactive elements.
ever screenshot --output ralph/screenshots/<page-name>.jpg
Actively test the feature with Ever CLI:

- Click buttons, open modals, expand dropdowns - Fill forms with test data, observe validation and responses - Try CRUD operations (create, read, update, delete) - Test search/filter/sort if present - Check empty states, loading states, error states - Test pagination/infinite scroll - Note animations, transitions, toasts/notifications - Use API keys from .env to test API features via curl

Screenshot key states: ralph/screenshots/<page-name>-<state>.jpg
Cross-reference what you see in the UI with what the docs say — the docs describe the feature, the UI shows how it's presented.

When to use what:

Task	Tool
Reading docs/help pages	`cat target-docs/<path>.md` (already scraped)
Reading API contract	`cat target-docs/openapi.json` (if present)
Mapping site structure	`ever snapshot` (read nav links)
Testing UI interactions	`ever snapshot` → `ever click` → `ever snapshot`
Testing API features	`curl` with API key from `.env`
Capturing visual reference	`ever screenshot`

Every Iteration: Update build-spec.md Incrementally

After each inspection iteration, update build-spec.md with what you know so far. This file grows as you discover more:

Add newly discovered pages to the site map
Add newly observed colors, fonts, components to the design system
Add newly discovered data fields to the data models
Update the feature list with new entries
Mark sections as "partial" or "complete" so future iterations know what's left

This ensures that if the inspect loop stops unexpectedly, there's still a usable (partial) spec.

Final Iteration: Clean Up build-spec.md & Reorder PRD

Once all features are inspected, do a final cleanup pass on build-spec.md:

Remove all "partial" markers
Consolidate duplicate observations
Ensure the design system is complete and consistent
Write a clear product overview now that you've seen everything
Finalize the tech stack recommendation

Step 1: Identify the CORE features of this product. Before reordering, first answer: "What is this product's reason to exist? What are the 3-5 features that make it valuable?"

For example, if cloning an email API platform:

Core: sending emails via API, viewing email logs, managing API keys
Secondary: domains, webhooks, team settings
Nice-to-have: analytics charts, contact lists

Or if cloning a CRM:

Core: contacts list, deal pipeline, activity feed
Secondary: reports, integrations, settings
Nice-to-have: email templates, automation rules

The core features MUST be built first and get the most build iterations. If the loop runs out of time, the core features are done and the product is still useful.

Step 2: Reorder prd.json by implementation order. Sort all entries so the build loop implements core features first:

Project scaffolding (package.json, config, framework setup)
Core layout shell (app container, routing, navigation skeleton)
Design system foundations (colors, typography, spacing, shared components)
Data models and state management for CORE features
CORE FEATURES — the 3-5 features that define what this product does

(implement these end-to-end: UI + API + data + tests)

Primary pages and navigation for core features
Secondary features (search, filters, sorting)
Supporting features (settings, configurations)
Interactions (modals, dropdowns, tooltips, toasts)
Edge cases (empty states, loading states, error handling)
Polish (animations, transitions, responsive)

Add a "priority" field (1 = first to build) to each entry reflecting this order. Also add a "core" field: true for the essential features, false for everything else.

Step 2: Create build-spec.md containing:

Product Overview: What the product does, who it's for
Tech Stack Recommendation: Based on what we observed, recommend the best stack for cloning
Site Map: All pages and their relationships
Design System: Colors, fonts, spacing, component patterns observed
Data Models: Entities and fields discovered from forms, tables, API responses
Feature List: Summary of all features referencing prd.json entry IDs
Build Order: The same priority order used to sort prd.json, with rationale

Output Files

prd.json

Array of feature entries, each with:

json

{
  "id": "feature-001",
  "category": "ui|nav|auth|data|crud|search|settings|layout|interaction|sdk|developer-experience|onboarding",
  "description": "Clear description of the feature",
  "page": "Which page this belongs to",
  "ui_details": "Components, layout, colors, spacing",
  "behavior": "What happens when user interacts — observed by testing",
  "data_model": "Fields and types from forms/tables",
  "priority": 1,
  "core": true,
  "needs_structure": true,
  "dependent_on": ["infra-001", "design-001"]
}

needs_structure — set to true for complex features that cannot be built and verified in a single pass. Examples:

Multi-step onboarding flows or wizards.
Core app layout with complex state management.
Auth setup with multiple providers and session logic.
Complex settings pages with many sub-sections.

When true, the build agent will break the feature into vertical slices before coding.

DO NOT include test specs in prd.json. The build agent writes its own tests based on behavior and ui_details. After building, the build agent logs what it tested and what needs deeper QA in qa-hints.json — the QA agent reads those hints.

dependent_on — list IDs of features this one depends on or shares components with (3-5 max). Examples:

A detail page depends on its list page and shared data table
An API route depends on the database schema and auth middleware
A filter component depends on the page it's used on

PRD Item Sizing — CRITICAL

Each PRD item must be small and focused. If a feature has too many steps, SPLIT it into multiple PRD items.

Rules:

MAX 4-5 verification steps per PRD item
MAX 2-3 unit tests per PRD item
MAX 2 e2e tests per PRD item
MAX 2 edge case tests per PRD item

If a feature is too big (e.g., "entire settings page"), break it into:

"Settings page layout and navigation"
"Settings: update display name"
"Settings: change notification preferences"

Small PRD items = small commits = tight feedback loops = working product.

ONE page/feature per iteration.
Be thorough — capture colors, layouts, component types, exact text content.
ACTIVELY USE the product — click, type, submit, navigate. Don't just look.
Record BEHAVIOR you observe, not just UI structure.
Always navigate back to unexplored sections each iteration.
Commit after every iteration.