debug-red-first

Name: debug-red-first
Availability: InStock
Author: panamini

Reproduce user symptoms with a failing test before fixing UI state bugs.

Updated May 4, 2026

Search Tags:#debugging #reproduction #invariants #ui state #minimal fix #guard rails #red test

Ready to run

npx skills add https://github.com/panamini/pi-tooling --skill debug-red-first

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: debug-red-first
Source: https://github.com/panamini/pi-tooling/tree/main/skills/debug-red-first
Command: npx skills add https://github.com/panamini/pi-tooling --skill debug-red-first

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents teams from “guess-fixing” unstable UI and state issues by requiring a concrete failing reproduction that matches the exact user symptom before any product change.

Core Features & Use Cases

Symptom-first debugging workflow: Lock the pass to one exact user symptom and one user-facing invariant.
RED test discipline: Write a failing test that reproduces the symptom on current code, then only proceed when it truly fails.
Minimal, shared-path fixes: Apply the smallest change, prioritizing shared source-of-truth and shared load/switch paths before local tweaks.

Quick Start

Run the debug pass by defining the exact user symptom and its user invariant, writing one RED failing test that reproduces it on current code, then applying only a minimal fix and re-running guard-rail tests plus a short manual smoke check.

Frequently Asked Questions about debug-red-first

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I fix inconsistent UI bugs when my tests are green but the user behavior still fails?▼

Fix inconsistent UI bugs by first defining the exact user symptom and one user-facing invariant, then writing a single RED failing test that reproduces the symptom on current code before applying any product change. This prevents guess-fixing unstable state issues.

What is the best way to reproduce flickering UI state jumps across multiple surfaces?▼

Reproduce flickering UI state jumps by locking the debug pass to one exact user symptom and writing a failing test that triggers the state jump on current code. You must verify the test truly fails before proceeding with a minimal fix along the shared path.

How do I stop guess-fixing unstable UI state issues like reordering under cursor?▼

Stop guess-fixing unstable UI state issues by requiring a concrete RED reproduction test that matches the exact reordering symptom. Apply only a minimal fix along the smallest responsible shared source-of-truth path, then re-run guard-rail tests and a short smoke check.

Can I apply local UI tweaks before writing a failing test for state jumps?▼

You should not apply local UI tweaks before writing a failing test. The workflow requires prioritizing shared source-of-truth and shared load/switch paths for minimal fixes only after a RED test reproduces the exact user symptom on current code.

Why do my UI tests pass but the real user behavior still fails with state jumps?▼

UI tests pass while real user behavior fails when tests do not cover the exact user symptom or invariant. The workflow solves this by requiring one RED failing test that precisely reproduces the user-facing symptom before any fix is applied.

Does this debugging workflow work for UI reordering under cursor and flicker issues?▼

Yes, this debugging workflow explicitly applies to scenarios with flicker, reordering under cursor, and state jumps across multiple surfaces. It requires symptom definition, a RED reproduction test, a minimal shared-path fix, and verification with adjacent guard rails.