| 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:
