JoshuaShepherd Stitch intake and gap audit
Ensure every in-scope route has a cached Stitch HTML + PNG mapped to the right route, with a gap report against the component checklist — before any conversion.
Scope from $ARGUMENTS (a screen set, cluster, or "all"); default to the full project.
Read first
From the target repo (values resolve via TENANT_MANIFEST.md):
docs/build/prompts/stitch-migration/TENANT_MANIFEST.md—{{STITCH_PROJECT_NAME}},{{STITCH_PROMPTS_HTML}}, route scope (in-scope / tenant-unique / excluded), legacy redirects.docs/build/prompts/stitch-migration/STITCH_ROUTE_INDEX.md— order ↔ route lookup.docs/build/prompts/stitch-migration/COMPONENT_CHECKLIST.md— required sections per route.- The Stitch prompt library at
{{STITCH_PROMPTS_HTML}}(thePROMPTS[].textentries define section order).
A. Fetch and cache (stitch-react Phase 0)
Use the Stitch MCP (stitch__list_projects / stitch__list_screens / stitch__get_screen)
or ask the user for the project id. For each screen:
get_screen→htmlCode.downloadUrl,screenshot.downloadUrl.- Save to
.stitch/designs/{page-slug}.{html,png,meta.json}. - Prefer
scripts/fetch-stitch.shif present; elsecurl -L.
Page-slug convention: lowercase, hyphenated from the screen title ("Homepage" → homepage).
The existing stitch-react skill (fetch-only mode) does exactly this — delegate to it
if available rather than re-implementing fetch logic.
B. Build the screen ↔ route map
Create / update docs/build/notes/stitch-screen-route-map.md:
| Stitch order | Screen title | page-slug | Next route | Scaffold status |
|---|---|---|---|---|
| 1 | Global chrome | global-chrome | layout | MISSING / CACHED |
| 2 | Homepage | homepage | / | PlaceholderPage |
Scaffold status = grep src/app for PlaceholderPage on that route.
C. Gap audit per route
For each mapped in-scope route, compare four signals:
- Sections in the Stitch prompt (
{{STITCH_PROMPTS_HTML}}→PROMPTS[].text). - Sections in
COMPONENT_CHECKLIST.md. - Sections present in the cached HTML (grep
data-section/ heading structure). - Current React page (
PlaceholderPage= 0% migrated).
Emit a gap table:
| Route | Required sections | In Stitch HTML | In React | Action |
|---|---|---|---|---|
| / | Hero, SocialProof, … | 7/8 | 0/8 | Convert + synthesize Newsletter |
D. Diagnose fake migrations
rg 'dangerouslySetInnerHTML|const html =| class=' src -l
Any hits → flag for real-JSX conversion in stitch-page-port.
Deliverables
.stitch/designs/populated (or a list of MISSING screens for a human to generate in Stitch).docs/build/notes/stitch-screen-route-map.md.docs/build/notes/stitch-gap-audit-<date>.mdwith a prioritized conversion order (Foundation/tokens → global chrome → home → pathways → content → courses → ai/chat/auth → utility/legal).
Do not
- Convert to React (that's
stitch-page-port). - Change
globals.csstokens (that'sstitch-token-bridge). - Port routes the manifest marks excluded (e.g. another tenant's unique route).
Acceptance criteria
- Screen ↔ route map exists for every in-scope route
- Each route has CACHED or MISSING documented
- Gap audit lists section-level deltas with actions
- No React conversion started here
Related skills
stitch-react (fetch primitive) · stitch-token-bridge · stitch-page-port ·
tenant-migration-playbook