UI Debug Workflow

UI Debug Workflow

When to Use

Use this skill when frontend behavior must be verified with reproducible evidence.

When Not to Use

Do not use this workflow for backend-only issues with no UI symptom.

Core Principles

1. Reproduce first, then modify code.
2. Capture baseline and changed evidence under the same conditions.
3. Compare artifacts before declaring a fix.
4. Document commands, environment, and outcomes.

Deterministic Workflow

1. Capture baseline evidence from a known branch.
2. Apply fix and capture changed evidence with identical steps.
3. Compare screenshots, DOM, and logs.
   • If comparison shows unexpected differences: 1) verify identical conditions (URL, viewport, seed data, build mode) 2) check for flaky or animated elements 3) re-capture both runs if needed before concluding.
4. Record pass/fail outcomes and unresolved risks.
5. Publish a concise report with links to artifacts.

Quick Commands

Install browser runtime for automation

npx playwright install chromium

Expected result: Chromium runtime is available for automated UI checks.

Capture baseline evidence

./skills/ui-debug-workflow/scripts/capture-evidence.sh baseline http://localhost:3000 ./baseline

Expected result: screenshots, DOM snapshots, and logs saved in ./baseline.

Capture changed evidence

./skills/ui-debug-workflow/scripts/capture-evidence.sh changed http://localhost:3000 ./changed

Expected result: comparable artifacts saved in ./changed.

Compare baseline vs changed artifacts

./skills/ui-debug-workflow/scripts/compare-evidence.sh ./baseline ./changed ./comparison.md

Expected result: comparison.md with summarized differences.

Run end-to-end debug session

./skills/ui-debug-workflow/scripts/full-debug-session.sh main fix/my-branch http://localhost:3000 "npm run build" "npm start"

Expected result: complete session output with report-ready evidence.

Evaluate this skill quality

sh skills/agentic-harness/skill-quality-auditor/scripts/evaluate.sh ui-debug-workflow --json

Expected result: updated score and grade.

Troubleshooting

capture-evidence.sh fails to run:

• Ensure the dev server is running and reachable at the target URL before executing the script.
• Check that the expected port is not occupied by another process (lsof -i :<port>).
• Confirm Chromium is installed (npx playwright install chromium).

compare-evidence.sh produces no output or errors:

• Verify both ./baseline and ./changed directories exist and contain artifacts.
• Re-run the capture steps if either directory is empty or incomplete.

Comparison reveals unexpected differences:

1. Confirm identical conditions: same URL, viewport size, seed data, and build mode.
2. Check for flaky elements (animations, timestamps, dynamic content) that may differ between runs.
3. Re-capture both baseline and changed runs under verified identical conditions before drawing conclusions.

Anti-Patterns

NEVER debug without deterministic reproduction steps

WHY: Non-reproducible issues cannot be verified or closed with confidence.

BAD: "I clicked around and it looked broken once." GOOD: "1) Open /users 2) Click Sort 3) Observe console error."

Consequence: Fixes become guesswork and regressions reappear.

NEVER skip console and network error review

WHY: Browser errors often reveal root cause faster than code browsing.

BAD: Edit components before checking runtime errors. GOOD: Inspect console/network first, then form hypothesis.

Consequence: Time is wasted on unrelated code paths.

NEVER compare baseline and changed runs under different conditions

WHY: Different data, viewport, or build mode invalidates comparisons.

BAD: Baseline on desktop, changed on mobile viewport. GOOD: Use identical URL, viewport, seed data, and commands.

Consequence: False positives and false negatives in debug conclusions.

NEVER close a UI fix without evidence artifacts

WHY: Unlogged fixes are hard to review and hard to trust.

BAD: Merge after manual spot-check with no screenshots/logs. GOOD: Attach baseline, changed, and comparison artifacts.

Consequence: Stakeholders cannot verify what changed.

References

• references/debugging-checklist.md
• references/browser-devtools-guide.md
• references/evidence-templates.md