​

Four-Stream Verification Methodology Caught Five SVG Bugs That Single-Pass Review Missed

​

The Bugs Found

When redesigning the oompa.tools command relationship graph (31 slash commands, d3-force physics simulation, chocolate/gold design tokens), a traditional single-pass review would have shipped with these bugs intact:

​

1. d3-force Edge Mutation (Silent Data Loss)

The bug: d3-force mutates link.source and link.target from strings to node objects after simulation. Code checking edge.source === hoveredNodeId (string comparison) fails 100% of the time because edge.source is now an object. Impact: Hover highlighting on edges doesn’t work. Users see the node glow but not the connected edges. Finding method: Stream 3 (Critical Gap Review) — Asked “What could silently fail in a force simulation?” Traced d3-force source code and discovered the mutation pattern.

​

2. Tooltip Clipping at ViewBox Boundaries

The bug: Tooltips positioned at node.y - 50px clip at the top edge (nodes have y >= 30px after clamping, so tooltip top = -20px). Impact: On-screen tooltips are cut off. Users see half-height tooltip boxes. Finding method: Stream 2 (Alternative Approach) — Implemented “defensive positioning” with edge detection and flip-below logic. Exposed the assumption that node.y - 50 is always visible.

​

3. Duplicate <style> Tag Injection

The bug: @keyframes fadeInSlide injected inside .map() loop, repeated ~50 times per render in the mobile fallback section. Impact: Massive stylesheet bloat, potential parser thrashing, unnecessary DOM mutations. Finding method: Stream 1 (Primary Research) — Audited the entire component structure and noticed the style block was inside the return statement of a map loop.

​

4. Dead CSS on SVG Elements

The bug: ring-2 ring-factory-gold-500 Tailwind class applied to <circle> element. Box-shadow (which ring-* generates) doesn’t apply to SVG elements. Impact: Visual inconsistency — hover state doesn’t show the expected highlight ring. Finding method: Stream 4 (Factual Audit) — Verified CSS spec: box-shadow is a CSS property, not an SVG paint server. Tailwind utilities generate CSS, not SVG filters.

​

5. SVG Text fill Attribute Overridden by Tailwind Classes

The bug: Text elements had className="text-white" in addition to fill="explicit color". CSS class specificity is higher than inline attributes in some browsers, causing color override. Impact: Text color doesn’t match the intended contrast logic. Finding method: Stream 3 (Critical Gap Review) — Asked “What’s the specificity hierarchy for SVG elements?” Discovered that inline attributes have lower specificity than CSS rules in the cascade.

---

​

The 4-Stream Methodology

​

Stream 1: Primary Research

Goal: Understand the design intent and current implementation. Read code, architecture, design system tokens. Questions:

• What is this component trying to do?
• What are the inputs (data, props, config)?
• What are the design constraints?
• Are there existing similar components?

Oompa case: Understood d3-force graph with 31 command nodes, 6 categories, chocolate/gold color system. Identified that the original design used circles + 2-letter labels, which caused collision issues. Deliverable: Summary of current architecture, constraints, and known issues.

---

​

Stream 2: Alternative Approach

Goal: Propose a completely different solution to the same problem. Don’t optimize the existing approach; replace it. Questions:

• What if we used Canvas instead of SVG?
• What if we used a different physics library?
• What if we changed the visual representation entirely?
• What assumptions is the primary approach making?

Oompa case: Proposed using pill-shaped nodes instead of circles, full /command names instead of 2-letter abbreviations. This forced re-examination of:

• Text layout and wrapping
• Node collision detection (rectangle vs circle)
• Horizontal scrolling/viewBox requirements
• Dark mode text contrast on varied background colors

Key discovery: The alternative approach revealed that “text contrast for light vs dark backgrounds” was an unexamined assumption in the primary design. Deliverable: Alternative design proposal with pros/cons vs. primary approach.

---

​

Stream 3: Critical Gap Review

Goal: Identify edge cases, failure modes, and assumptions that the primary and alternative approaches both missed. Questions:

• What could fail silently?
• What edge cases exist?
• What are the invariants that must hold?
• What assumptions are we making about data or environment?
• What happens at scale (max nodes, max edges)?

Oompa case: Asked “What could break in a force simulation?” Traced d3-force source and found the edge mutation bug. Asked “Where can tooltips clip?” and found the viewBox boundary issue. Asked “What happens if we use CSS classes on SVG?” and found the specificity problem. Deliverable: List of potential failure modes with risk assessment.

---

​

Stream 4: Factual Audit

Goal: Verify every claim against actual specifications, not assumptions. Check browser behavior, library APIs, CSS specs, accessibility rules. Questions:

• Does this CSS property actually work on SVG elements?
• Does d3-force really mutate the link object?
• Does Tailwind’s dark: class work inside SVG?
• Are the WCAG contrast ratios actually 4.5:1 for this color pair?

Oompa case: Verified CSS spec for box-shadow on SVG (doesn’t work). Verified d3-force mutation behavior by reading source code. Verified HSL color contrast ratios using WCAG formulas. Deliverable: Fact sheet confirming or refuting each major claim.

---

​

Reconciliation: Where Streams Disagreed

---

​

Why Single-Pass Review Misses These

1. d3-force mutation: Requires reading the library source or testing behavior. Static code review won’t catch it.
2. Tooltip clipping: Requires running the component at edge coordinates or doing manual math.
3. Duplicate styles: Easy to spot if you’re looking for it, but easy to miss if scanning for logic bugs.
4. Dead CSS classes: Requires knowing both Tailwind and SVG specs. Reviews often assume “if it’s in the code, someone tested it.”
5. SVG text specificity: Requires understanding CSS cascade + SVG scope isolation. Not obvious from code alone.

A traditional review (one engineer reading the PR) would likely catch 1–2 of these. The 4-stream approach guaranteed all 5 were surfaced before any code was written.

---

​

How to Apply This in Your Workflow

​

For Complex Frontend Tasks

If your task involves graphics (SVG, Canvas), animations, state management, or third-party library integration, use 4-stream verification before coding:

1. Assign Stream 1 to the primary engineer (read the codebase, design docs)
2. Assign Stream 2 to propose a completely different approach (think hard, don’t optimize)
3. Assign Stream 3 to find edge cases (what could fail? what assumptions?)
4. Assign Stream 4 to audit facts (verify claims against specs)

Run them in parallel. Merge findings into a single “Assumptions & Risks” table before coding starts.

​

For Simpler Tasks

If your task is straightforward (CRUD endpoints, form components, data transformations), traditional code review is sufficient.

​

Output Artifact

Create a Verification Summary table at the start of your work plan: This table becomes part of the permanent record and helps future teams avoid rediscovering the same issues.

---

​

Metrics (This Session)

• Bugs found via 4-stream methodology: 5
• Bugs that would have shipped in production: 4 (d3-force, tooltip clip, dead CSS, text specificity)
• Time investment: 90 minutes of parallel research + design (vs. 2+ weeks of QA/bug-fixing after ship)
• Files modified: 1 (command-graph.tsx, 194 insertions, 129 deletions)
• E2E tests: All 14 passing after fixes

---

​

Platform Impact

This methodology should be documented as a deployment gate for complex frontend work. Include in the PR template for data visualization, animation, and state-heavy components.