debugging-practices

name	debugging-practices
description	Load for ANY bug-fix task — code, UI/UX, content, docs, accessibility, or workflow. Reproduce → isolate → fix → prevent cycle with real-session patterns. GEPA-evolved from 353 real Claude Code session bugfixes (+31pp holdout).
version	1.0.0
evolved_by	GEPA
evolution_run	ab_test/output/run_20260620_100351
training_data	247 real bugfix observations (claude-mem, Mar–Jun 2026)
holdout_score	0.846
baseline_score	0.534
delta	+31.2pp
ab_test_winner	true

Debugging Practices (Field-Proven, Multi-Domain)

Overview

This skill delivers precise, actionable debugging steps for failures in software, content, documentation, UI/UX, and workflow. It addresses real-world, high-impact bug categories surfaced in AI coding sessions: logic, configuration, environment, specification drift, data/resource limits, content/policy errors, standards (accessibility, style guide) breaches, and UI/UX defects. Steps are designed for thorough root cause isolation and durable, verifiable fixes—including for micro bugs and compliance issues often missed by code-only approaches.

---

1. Reproduce and Gather Evidence

• Replicate the precise failure:
  • Use exact environment, inputs, config, file versions, and workflow steps.
  • For UI/content bugs, use the same browser, device, zoom, and accessibility settings as affected users.
• Collect artifacts:
  • Error/output logs, screenshots, terminal output, failing test cases, content diffs, and links.
  • Save both current and previous versions for side-by-side comparison.
  • For documentation/UI bugs, save broken screenshots, copy exact text, and note missing/incorrect elements.
• Document observed vs. expected outcome:
  • Write down the exact failure (e.g., "Last updated link is broken on updates.html", "Table header missing scope attribute", "SQL keywords lowercased against style guide").

---

2. Isolate and Categorize the Bug

a. Find the Source

• Code/Config/Workflow:
  • Use git bisect, file diffs, rollback, or minimal working examples to locate the change that introduced the bug.
  • For process/workflow: Audit each step; compare actual vs. required outputs (e.g., agent modifying read-only input).
• Content/Documentation/UI:
  • Use diff tools to spot changes in text, markup, alt-text, table structure, etc.
  • For visual/UI bugs, compare screenshots or run visual regression tools (Percy, Storybook, jest-image-snapshot).

b. Categorize (with concrete, real-case examples)

Logic or Implementation Bugs

• Validate all invariants:
  • Confirm permissions, data shape, unique keys.
  • Regression example: Fixing a broken template literal in a deduplication key.
• Log/print all intermediates: