>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588777. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The migrate-site skill has no mandated intermediate phase where page-level Storybook stories are assembled and reviewed before the content-composer pushes pages to the CMS. The first time anyone sees the full page layout is in the deployed CMS &mdash; where the fix-upload-CDN-wait cycle costs 10+ minutes per iteration.</p> <p>The skill's stated philosophy is "design in Storybook first, deploy to CMS second." In a recorded session this never happened: components were built in Phase 3 and immediately sent to the CMS in Phase 7 without any page-level Storybook preview. The <code>Home.stories.tsx</code> was left as generic canvas-starter boilerplate ("Welcome to Our Site", "Service One", placehold.co images) &mdash; meaning the component library looked like a blank template, not a target-site clone. Four of eight pages were never composed at all.</p> <p>The fix was applied post-hoc in a later session (8 page-story agents dispatched in parallel and the page stories were retrofitted), but this was a post-migration fix, not built into the skill as a pre-composition gate. The skill needs a Phase 3.7 gate: page stories with real content must exist and look correct in Storybook before content-composer touches the CMS.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run the migrate-site skill end-to-end against any multi-page site.</li> <li>After Phase 3.5 completes, inspect <code>stories/pages/</code>.</li> <li>Observe: no page stories exist OR they contain canvas-starter boilerplate strings ("Welcome to Our Site", "Service One", "placehold.co") rather than real content.</li> <li>Observe: Phase 4 upload and Phase 7 CMS composition proceed without any gate failure.</li> <li>Open the deployed CMS &mdash; observe page-layout problems that would have been caught by a Storybook preview.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Add Phase 3.7 to <code>.claude/skills/migrate-site/SKILL.md</code></strong> between the Phase 3.5 QA gate and the Phase 4 upload:</p> <pre>PHASE 3.7 &mdash; Page-Level Storybook Story Assembly (mandatory gate before Phase 4) For each page in the page inventory: a. Create stories/pages/&lt;PageName&gt;.stories.tsx b. Use verbatim content from content/&lt;slug&gt;.md (NOT canvas-starter boilerplate) c. Compose components in correct order matching the source site layout d. Navigate localhost:6006 and verify the page renders with real content GATE CRITERIA (must ALL pass before proceeding to Phase 4): - All pages in the page inventory have a .stories.tsx file under stories/pages/ - No story file contains "Welcome to Our Site", "placehold.co", or "Service One" (canvas-starter boilerplate markers) - Every story renders without JS errors in Storybook - Homepage (/index) story is the first one verified by the orchestrator</pre><p><strong>Step 2 &mdash; Dispatch <code>page-story-composer</code> agents in parallel</strong> (4&ndash;6 per turn). The post-hoc fix demonstrated this pattern works at scale (9 agents in a single turn).</p> <p><strong>Step 3 &mdash; Add boilerplate-detection to <code>.claude/agents/artifact-checker.md</code>:</strong> grep page stories for the known canvas-starter strings and fail the Phase 3.7 gate if any are found.</p> <p><strong>Step 4 &mdash; After the Phase 3.7 gate passes,</strong> Phase 4 upload and Phase 7 CMS composition may proceed. Page stories then serve as the visual spec for content-composer agents: <em>"your CMS output should match this Storybook story."</em></p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the Phase 3.7 block to <code>SKILL.md</code> with the full gate-criteria list.</li> <li>Define a <code>page-story-composer</code> agent (or extend <code>component-builder.md</code>) for the page-story task: read <code>content/&lt;slug&gt;.md</code> verbatim, compose components in source-site order, write <code>stories/pages/&lt;PageName&gt;.stories.tsx</code>.</li> <li>Add the boilerplate-detection check to <code>artifact-checker.md</code> for Phase 3.7.</li> <li>Verify on a fresh run: <code>localhost:6006</code> shows a story under <code>stories/pages/</code> for every page in the inventory.</li> <li>Verify the gate blocks Phase 4: deleting one page story or leaving boilerplate strings in place must cause Phase 4 upload to refuse to start.</li> <li>Verify homepage story is composed first by the orchestrator.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>Storybook gains a <code>Pages/&lt;Name&gt;</code> top-level group with one story per source-site page, populated with real content. This is the new pre-CMS visual artifact.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifact directory: <code>stories/pages/</code> with <code>&lt;PageName&gt;.stories.tsx</code> files. New gate-output artifact: a Phase 3.7 gate JSON listing per-page pass/fail with boilerplate-string detection results.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-3-Visual-Fidelity/02-page-level-storybook-stories-not-created-before-cms-composition.md</code> (id: P1-12)</li> <li>Deep analysis: <code>RESEARCH-2026-04-28/00-existing-issues/prior-deep-analysis-key-points.md</code> (HIGH finding on Storybook-first workflow; P0 recommendation 0b)</li> <li>Post-hoc fix evidence: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half2/what-was-fixed-in-second-session.md</code> (8 parallel page-story agents at L606)</li> <li>Actionable list: <code>RESEARCH-2026-04-28/99-final/actionable-list.md</code> (P1-12 row)</li> <li>Recommendation source: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (SKILL.md Phase 3 &rarr; Phase 7 flow context)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P1 (Screenshot to Storybook Organism in Under 15 Minutes)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P3 (Atomic Story Structure Works When the Flat Directory Is Removed First)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P12 (Self-Aware Retrospective Design &mdash; Phase 3.5 QA Loop)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Should Phase 3.7 run before or after Phase 3.5 (QA loop)? Suggested: Phase 3.5 fixes individual components &rarr; Phase 3.7 assembles pages. If a component still has an open unfixed issue, the page story may still be assembled with a note about the open issue.</li> <li>The <code>component-builder</code> spec already says "After ALL components for a page have been individually verified: Compose the page story" &mdash; but this is per-component. Confirm the Phase 3.7 gate is a batch pass over ALL pages and replaces the optional per-component step.</li> </ul>