>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588779. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The Ralph Loop runs with <code>max_iterations: 0</code> (unlimited) and pushes multi-component changes in each iteration without per-component verification. Visual regressions occur where the site looks worse after a fix pass than before &mdash; a failure the user explicitly named as <em>"your analysis broke the site more, things look more disoriented and not in place than before."</em></p> <p>This pattern occurred in at least three recorded sessions:</p> <ul> <li>The "broke it more" complaint appeared at two different compaction summaries in the same project (recorded at L10600 and L11268), making clear it survived multiple iterations and re-rolls.</li> <li>In another project, a VideoCard with a text-below-image structural inversion survived multiple ralph-loop iterations undetected &mdash; the QA loop produced false confidence while the underlying issue persisted unchanged.</li> <li>In a third project, the agent hallucinated elements (red border, divider line) that do not exist in the reference and propagated those edits across multiple components.</li> </ul> <p>The root failure is the same in all three: the Ralph Loop architecture optimizes for "fix many things at once" rather than "fix one thing and verify." The skill already says <em>"Follow incremental deployment (one component at a time)"</em> and <em>"Verify after every upload"</em> &mdash; but the Ralph Loop's unlimited-iterations architecture actively undermines this instruction by rewarding throughput over precision.</p> <p>This is a P0/Critical because it actively degrades work already done. Sprint 3 addresses the architectural fix: one component at a time, with verification before proceeding, and a pre-fix baseline so regressions are detectable.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Start a Ralph Loop session against a site with multiple components needing fixes.</li> <li>Allow the loop to run for several iterations.</li> <li>Inspect the diff per iteration: each iteration touches multiple components and uploads them together.</li> <li>After upload, navigate the live CMS and compare to a screenshot taken before the loop ran.</li> <li>Observe: the live page shows visible regressions in components that were not the targeted fix (alignment shifts, spacing collisions, hallucinated elements).</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Add an UPLOAD DISCIPLINE block to <code>visual-verifier.md</code> and <code>component-fixer.md</code></strong> (verbatim from the recommendation source):</p> <pre>UPLOAD DISCIPLINE: Change ONE component at a time. Upload it. Verify it. THEN proceed to the next component. NEVER: - Change multiple components in a single sweep and upload together - Report a component fixed without visual verification on the live CMS This prevents the "broke the site more" regression pattern where parallel changes interact in unexpected ways.</pre><p><strong>Step 2 &mdash; Add a pre-fix capture step to <code>component-fixer.md</code>:</strong></p> <ul> <li>Before any code change: <code>mcp__chrome-devtools__take_screenshot</code> of the current state &rarr; write to <code>docs/migration/components/&lt;name&gt;/revisions/&lt;N&gt;-pre.png</code>.</li> <li>After fix + upload + verify: take post-fix screenshot &rarr; write to <code>revisions/&lt;N&gt;-post.png</code>.</li> <li>Log both paths to the issue file: <code>pre-fix: revisions/1-pre.png, post-fix: revisions/1-post.png</code>.</li> <li>If post-fix looks visually worse than pre-fix &rarr; flag as REGRESSION, do NOT commit, revert and analyze.</li> </ul> <p><strong>Step 3 &mdash; Add to the Ralph Loop prompt:</strong> <em>"Before taking a screenshot comparison pass, run the Tier 1 structural check (DOM element order) for each section. If a structural mismatch is found, fix THAT SECTION ONLY before proceeding to the next. Do not accumulate fixes across multiple components and push them together."</em></p> <p><strong>Step 4 &mdash; Change Ralph Loop default from <code>max_iterations: 0</code> to <code>max_iterations: 3</code></strong> as a safety default. This limits blast radius when the loop is not making progress (paired with Sprint 4 P2-4).</p> <p><strong>Step 5 &mdash; Add regression detection logic:</strong> after each component fix, compare source similarity score. If the similarity score (e.g., pixel diff percentage or CSS delta sum) is WORSE after the fix than before, log <code>REGRESSION DETECTED</code> and halt that component's fix loop pending user review.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the UPLOAD DISCIPLINE block to <code>.claude/agents/visual-verifier.md</code> and <code>.claude/agents/component-fixer.md</code>.</li> <li>Add the pre-fix / post-fix capture step (with the <code>revisions/&lt;N&gt;-pre.png</code> / <code>&lt;N&gt;-post.png</code> convention) to <code>component-fixer.md</code>.</li> <li>Add the single-component discipline to the Ralph Loop prompt itself (<code>.claude/ralph-loop.local.md</code> or equivalent).</li> <li>Change Ralph Loop <code>max_iterations</code> default to <code>3</code>.</li> <li>Optionally add a regression-guard script to <code>scripts/</code> that compares pixel similarity of post-fix vs pre-fix vs source and flags divergence.</li> <li>Verify by deliberately changing two components at once: the updated agent must refuse and enforce one-at-a-time.</li> <li>Verify by deliberately introducing a regression: the agent flags the regression and halts rather than declaring "fixed."</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None directly. The user-visible result is fewer regressions on the deployed CMS site.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New per-component artifact directory: <code>docs/migration/components/&lt;name&gt;/revisions/</code> with <code>&lt;N&gt;-pre.png</code> and <code>&lt;N&gt;-post.png</code> entries (formalised in 3-05). New issue-file fields: <code>pre-fix</code> and <code>post-fix</code> path entries. Configuration change: Ralph Loop <code>max_iterations</code> default 0 &rarr; 3.</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/04-aggressive-multi-component-changes-regress-site.md</code> (id: P0-8)</li> <li>"Broke it more" verbatim user feedback: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half2/user-feedback.md</code> (L10600, L11268)</li> <li>Sweep-quality user feedback: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/user-feedback.md</code> (L4855)</li> <li>Issues-found analysis: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/issues-found.md</code> (A8 Ralph Loop with no completion condition; A9 aggressive parallel changes)</li> <li>Findings: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/findings.md</code> (F13)</li> <li>Layout-inversion + hallucination evidence: <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/dbc7a979/issues-found.md</code> (CRITICAL-2, CRITICAL-3, L2045 verbatim)</li> <li>Consolidated root cause: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> (P0-8 entry)</li> <li>Working implementation reference: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q3-records-5768-to-8651/visual-fidelity-iteration-pattern.md</code></li> <li>Recommendation source: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (<code>.claude/agents/visual-verifier.md</code> UPLOAD DISCIPLINE block)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P12 (component-fixer scoped to ONE issue per invocation)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P18 (Structural DOM-Order Check Before Pixel Comparison)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>The SKILL.md already says "one component at a time" but the Ralph Loop prompt overrides this by incentivizing comprehensive fixes. The Ralph Loop prompt is user-authored &mdash; confirm the single-component discipline is added to the Ralph Loop prompt itself, not only to the agent files.</li> <li>The pre-fix screenshot requires navigating to the live CMS URL. If the CMS does not yet have the component (pre-upload phase), the pre-fix baseline must be the Storybook render instead. Clarify in the agent instructions: "if CMS is not yet available, use Storybook for pre-fix baseline."</li> </ul>