project-debug

Follow a phased protocol: observe evidence read-only, rank 2-5 hypotheses by likelihood, run single-variable experiments to confirm one root cause, then implement a minimal approved fix and verify it. This prevents speculative changes that mask symptoms.

Screenshot the current state via Chrome MCP, then inspect computed styles, DOM structure, and transition states to narrow the cause. Check for view-transition-name conflicts, z-index stacking, and lazy-load re-renders, and prefer CSS-only fixes over JavaScript workarounds.

setTimeout delays execution to avoid a problem rather than solving it, making it a bandaid that hides the real render lifecycle or timing issue. The protocol requires finding the actual root cause and flags any workaround explicitly if a proper fix is not feasible.

Code changes are only allowed in the fix phase, after the root cause is confirmed with high confidence through read-only observation and narrowing experiments. The developer must approve the proposed minimal change before implementation.

If verification fails, the protocol returns to the narrowing phase instead of iterating blindly on the same fix. Retrying the same approach is an anti-pattern; one revert means stepping back to re-investigate the hypothesis ranking.