>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588776. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The <code>storybook-qa</code> agent files issues without always capturing a built screenshot at the time of filing, leaving the <code>component-fixer</code> agent working with incomplete information and no before/after baseline. By the time <code>component-fixer</code> reads the issue file, the component may already have been changed since the issue was filed &mdash; making the issue stale or the description misleading. Without a built screenshot at filing time, there is no baseline to compare against after a fix is applied: the fixer cannot prove the fix moved toward the source, and it cannot detect regressions.</p> <p>Concrete evidence: in a recorded session, two issues (Issues 04 and 06) had no built screenshots at all. Issue 06 had only an <code>issue.md</code> with no images at any viewport. The deep-analysis table records: <em>Issue 04 (missing story): source screenshot YES, built screenshot NO; Issue 06 (badges oversized): source screenshot NO, built screenshot NO, before-fix built NO.</em></p> <p>The user's verbatim request for a "revisions system" identifies this gap as the foundation that any such system needs to build on: <em>"component iteration should be build with a revisions system or something not complete git tracking but something as simple as: COMPARE: Old/previous, current &amp; new component to properly break down the differences and see if the change actually fixed it."</em></p> <p>This is the smallest, most direct fix in Sprint 3 and unblocks 3-03, 3-04, and 3-05.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run a migrate-site session through Phase 3.5 (storybook-qa) on a component library with at least one obvious visual mismatch.</li> <li>Inspect the resulting <code>docs/migration/issues/issue-NNN-*.md</code> files.</li> <li>Observe: at least one issue file has only a text description and a <code>source_screenshot</code> field (or neither), with no <code>built_screenshot</code> path populated.</li> <li>Pass the issue to <code>component-fixer</code>. Observe: the fixer proceeds without a baseline and reports "fixed" without any before/after comparison.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Update <code>storybook-qa.md</code> with a mandatory Issue Filing Protocol (verbatim from the recommendation source):</strong></p> <pre>ISSUE FILING PROTOCOL (mandatory): Before filing any issue: 1. Capture source screenshot at this section/component (if not already in bundle) 2. Capture current built screenshot in Storybook 3. Write both to the issue file: source_screenshot: docs/migration/components/&lt;name&gt;/screenshot-1440.png built_screenshot: docs/migration/issues/issue-NNN-built.png Issue files with no built_screenshot MUST NOT be filed. Component-fixer will reject issues without this artifact.</pre><p><strong>Step 2 &mdash; Update <code>component-fixer.md</code> with a baseline guard:</strong> before starting any fix, check that the file referenced by <code>built_screenshot</code> exists on disk. If absent, log a warning, re-run <code>storybook-qa</code> to capture the current state, then proceed. Never skip the baseline capture silently.</p> <p><strong>Step 3 &mdash; Update the issue file template</strong> in the skill to make these required fields rather than optional comments:</p> <pre>source_screenshot: docs/migration/components/&lt;name&gt;/screenshot-1440.png built_screenshot: docs/migration/issues/issue-NNN-&lt;component&gt;-built.png description: | [text description]</pre><p><strong>Step 4 &mdash; Add to the Phase 3.5 gate criteria:</strong> "All issue files must have both <code>source_screenshot</code> and <code>built_screenshot</code> populated. Gate FAILS if any issue file is missing either field."</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the mandatory Issue Filing Protocol block to <code>.claude/agents/storybook-qa.md</code>.</li> <li>Add the baseline guard to <code>.claude/agents/component-fixer.md</code>.</li> <li>Update the issue file template in the skill to mark <code>source_screenshot</code> and <code>built_screenshot</code> as required.</li> <li>Add the both-fields-populated check to the Phase 3.5 gate artifact-checker.</li> <li>Verify on a fresh run: every issue file has both fields populated and both files exist on disk.</li> <li>Verify the fixer guard: deleting <code>built_screenshot</code> on disk and invoking <code>component-fixer</code> causes a re-capture, not a silent proceed.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None. Existing screenshot tooling is sufficient.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>Two issue-file fields are promoted from optional to required: <code>source_screenshot</code> and <code>built_screenshot</code>. New PNG artifact per filed issue: <code>docs/migration/issues/issue-NNN-&lt;component&gt;-built.png</code>.</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/01-issue-files-missing-before-fix-screenshots.md</code> (id: P1-6)</li> <li>Deep analysis: <code>RESEARCH-2026-04-28/00-existing-issues/prior-deep-analysis-key-points.md</code> (MEDIUM finding on Issues 04/06; P1 recommendation #10)</li> <li>User note: <code>RESEARCH-2026-04-28/00-existing-issues/unsorted-issues.md</code> (Thread 4 verbatim revisions request)</li> <li>Recommended verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (<code>.claude/agents/storybook-qa.md</code> ISSUE FILING PROTOCOL)</li> <li>Original issues evidence: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/issues-found.md</code> (Issues 04 and 06)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P15 (Commit-Anchored QA &mdash; Screenshots as Repository Artifacts)</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>Are there existing issue files from prior sessions that need to be backfilled with screenshots, or do we only apply the protocol going forward?</li> <li>Does <code>storybook-qa</code> have access to the Storybook localhost port when it runs, or does it need to start the dev server first? Verify the agent definition covers server-start in its preflight.</li> </ul>