>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588758. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The site-analyzer correctly discovers all source-site sections in its inventory but only creates full capture bundles (screenshot + HTML + computed-styles) for a small subset. In a recorded session it found 28 sections across 8 pages and accurately documented them in <code>plan.md</code>, then captured bundles for only 5: <code>site-header</code>, <code>site-footer</code>, <code>hero-section</code>, <code>cta-section</code>, <code>blog-grid</code>.</p> <p>The 23 missing sections include: "Team member grid (about &mdash; New)", "YouTube video embed section (home &mdash; New)", "Contact form section (contact-us &mdash; New)", "Pricing/packages table (subscriptions &mdash; New)", and others. These are all <code>New</code> or <code>Extend</code> classification &mdash; exactly the sections that need the most reference material because a similar component does not already exist. The component-builder agents had to work from DOM inspection alone for these sections, and the quality gap was directly visible in the resulting incomplete composition.</p> <p>A fresh second-session run hit the same failure &mdash; because the agent definition was never updated. This will repeat on every new migration run unless the skip heuristic is corrected.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run the migrate-site skill against any multi-section site (e.g., freelygive.io with 28 sections / 8 pages).</li> <li>After Phase 1 completes, list <code>docs/migration/components/</code> directories.</li> <li>Compare to the section count in <code>plan.md</code>'s page inventory.</li> <li>Observe: <code>New</code>/<code>Extend</code> sections are missing capture bundles.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Replace the current "covered by an existing component &rarr; skip capture" heuristic with an explicit BUNDLE CAPTURE RULE in <code>.claude/agents/site-analyzer.md</code>:</p> <pre>BUNDLE CAPTURE RULE: For every section in the Page Inventory: - "New" or "Extend" classification: ALWAYS capture full bundle (screenshot + HTML + computed-styles) - "Reuse-unchanged" classification: capture screenshot-only bundle - "Skip" classification: no capture needed DO NOT use "already covered by existing component" as a reason to skip a bundle for any New or Extend section. The component-builder needs reference screenshots even for sections that extend existing components. Post-capture verification: count(sections-with-full-bundles) must equal count(New) + count(Extend)</pre><p>The bug is that the current skip heuristic fires incorrectly on "similar but needs extension" cases. An <code>Extend</code> section is one where an existing component is close but needs modification &mdash; and the component-builder still needs a reference screenshot to understand what modifications are required.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the BUNDLE CAPTURE RULE block to <code>.claude/agents/site-analyzer.md</code>; remove or invert the "covered by existing component &rarr; skip" heuristic.</li> <li>Update <code>.claude/skills/bundle-capture/SKILL.md</code> if it exists as a separate file.</li> <li>If the skip logic is in <code>scripts/capture-component-bundle.mjs</code> rather than agent instructions, fix it there.</li> <li>Add the post-capture coverage check as a Phase 1 hard-gate condition in <code>SKILL.md</code>: <code>BUNDLE COVERAGE: N of M New/Extend sections bundled. Expected: N=M.</code> Phase 1 cannot proceed if the count fails.</li> <li>Verify on a target site: every <code>New</code> and <code>Extend</code> section has <code>screenshot-1440.png</code> + <code>snapshot.html</code> + <code>computed-styles.json</code>.</li> <li>Verify <code>Reuse-unchanged</code> sections still get lightweight (screenshot-only) bundles &mdash; confirm the heuristic is not over-corrected.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New required field in Phase 1 summary: <code>bundle_coverage: {expected: N, actual: M}</code>. New gate-failure condition if <code>actual &lt; expected</code>.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-1-Foundations/03-P0-1-site-analyzer-under-captures-bundles.md</code> (id: P0-1)</li> <li>Deep analysis: <code>RESEARCH-2026-04-28/00-existing-issues/prior-deep-analysis-key-points.md</code> (table of 28 sections; 5 bundled vs 23 missed)</li> <li>Second-session evidence: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/findings.md</code> (F6, F4)</li> <li>Recommended verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (BUNDLE CAPTURE RULE)</li> <li>Theme analysis: <code>RESEARCH-2026-04-28/00-existing-issues/issue-themes.md</code> (Theme 4)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/patterns.md</code> &sect; A1 (Compaction Erases "Why")</li> <li>Anti-pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/session-anti-patterns.md</code> &sect; AP3 (AI Hallucinating Visual Elements)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Is the skip heuristic implemented in agent instructions or in a script? Determines whether the fix is text-only or also needs code change.</li> <li>Bundle capture happens during Phase 1 (before the gap analysis classifications from Phase 2 exist). Is there a preliminary classification in Phase 1, or does bundle capture need to be deferred to after Phase 2? May require a SKILL.md phase restructure.</li> <li>What classification did the remaining 15 sections (out of 28 total, minus 5 captured and 8 missed) have? Determines the verification count.</li> </ul>