Use when a user reports a non-CSS UI bug in a Next.js App Router application — "blank page," "data not loading," "click does nothing," "hydration mismatch," "flicker on navigation," or "state not updating." Runs symptom-targeted diagnostic checks against a component map to identify rendering, state, event handling, and data flow issues. Not for CSS layout, styling, or visual design problems — route those to css-layout-debugger.
Diagnose non-CSS UI bugs by running symptom-targeted checks against the component map. Produce a DiagnosisReport with FLAGGED/CLEAR/SKIPPED findings.
.claude/qa-cache/artifacts/ for DiagnosisReport persistence@radix-ui, shadcn/ui, @mui, etc.).claude/qa-cache/component-maps/{route-slug}.jsonCopy this checklist and update as you complete each step:
Progress:
- [ ] Step 1: Consume Component Map
- [ ] Step 2: Classify Symptom
- [ ] Step 3: Identify Target Components
- [ ] Step 4: Run Checks
- [ ] Step 5: Assess Confidence
- [ ] Step 6: Output DiagnosisReport
- [ ] Step 7: Persist Artifact
Note: If you've lost context of previous steps (e.g., after context compaction), check the progress checklist above. Resume from the last unchecked item. Re-read relevant reference files if needed.
Read the ComponentMap artifact from .claude/qa-cache/component-maps/.
Check completeness:
"partial" or "shallow": warn the user — "Component map is {completeness} ({N} unresolved imports). Diagnosis may miss components behind unresolved imports. Run --depth N on the mapper for deeper tracing.""full": proceed silently.Map the user's reported symptom to one or more diagnostic categories:
| Symptom Signal | Primary Category | Reference to Load |
|---|---|---|
| Blank/missing content, wrong content shown, flicker on load, content appears then disappears | Rendering & State | references/rendering-state-checks.md |
| Click/tap does nothing, wrong handler fires, keyboard nav broken, focus lost | Event Handling | references/event-handling-checks.md |
| Stale data, missing data, wrong data, loading never resolves, data appears in wrong component | Data Flow | references/data-flow-checks.md |
| Hydration mismatch warning in console | Rendering & State | references/rendering-state-checks.md |
| Component works in dev but not in production build | Data Flow + Rendering | Load both references sequentially |
| Unknown or ambiguous | All three | Load in order: rendering → data-flow → event-handling |
If the symptom clearly maps to a single category, load only that reference. Do not run all checks when one category is sufficient.
From the ComponentMap, select the components to investigate:
@radix-ui, shadcn/ui, @mui, etc.Target 3-8 components. If more than 8 are plausible, narrow by asking the user one question.
Read the reference file(s) identified in Step 2. For each target component, apply the relevant checklist items from the reference.
For each check:
Stop checking a component after the first FLAGGED item with High confidence. Continue checking other components.
For each FLAGGED finding, assign confidence:
Present findings in this order:
## Diagnosis: [symptom restated]
FLAGGED [file:line] — [description]
[2-3 sentence explanation]
Evidence: [observation 1] | [observation 2] | [observation 3]
CLEAR [ComponentName] ([file]) — [reason cleared]
CLEAR [ComponentName] ([file]) — [reason cleared]
SKIPPED [Category] — [reason]
Checked: [N] components ([categories]) | Not checked: [categories] | Confidence: [High/Medium/Low]
If multiple FLAGGED findings: list the highest-confidence one first. If no FLAGGED findings, output the inconclusive format:
## Diagnosis: Inconclusive
Investigated [N] components across [categories]. No root cause identified.
What might help:
- [specific ask 1]
- [specific ask 2]
- [specific ask 3]
Checked: [N] components ([categories]) | Not checked: [categories] | Confidence: --
Save the DiagnosisReport to .claude/qa-cache/artifacts/diag-{timestamp}-{id}.json with:
version: "1.0"skill: "ui-bug-investigator"issueClassification: the category from Step 2rootCause: the highest-confidence FLAGGED finding (or null)differentialDiagnosis: all CLEAR items with their cleared reasonssuggestedFix: a one-line description of what to change (consumed by component-fix-and-verify)Pass the DiagnosisReport artifact path to qa-coordinator. The report contains structured rootCause, differentialDiagnosis, and suggestedFix fields consumed by component-fix-and-verify.
| Path | Load Condition | Content Summary |
|---|---|---|
references/rendering-state-checks.md | Symptom is rendering, state, or hydration | Checklist for boundary mismatches, key props, conditional rendering, hydration |
references/event-handling-checks.md | Symptom is click/keyboard/focus issues | Checklist for handler attachment, propagation, focus management |
references/data-flow-checks.md | Symptom is data loading, staleness, or missing data | Checklist for fetch patterns, caching, server actions, prop threading |