Evidence-Driven Bug Fixing

Requirements

For Codex-class agents with repository and file access capabilities. The file does not provide browser, test tools, credentials, project data, or permission to modify external systems; other hosts may need adaptation.

Failure entry, inputs, expected and actual results, as well as environment and version
Access to relevant code and logs; when symptoms involve the UI, a real browser or target app is required
If code modification is required, explicit fix authorization is needed

Quick start

After downloading, first check the in-package documentation, then extract the ZIP to a temporary directory.
When installing the combined set, copy the six Skill folders and the sibling shared folder into the project's .agents/skills/ or personal ~/.agents/skills/. Keep the relative directory structure; do not treat the outer folder of the combined set as one Skill.
When installing an individual ZIP, put the same-named folder into the selected Skills directory and keep its internal shared resources. Back up the same-named Skill before overwriting to avoid duplicate installation.
In Codex, use the exact $bug-fixing call; if not found, restart the host. When the task requires workflow handoff, install the corresponding companion Skill separately.

Applicable Scenarios

Clear failure inputs or reproducible regression issues from user operations
Inconsistencies among UI, API, and data, stale data reappearing after refresh, or intermittent asynchronous failures

Usage Steps

Call $bug-fixing, providing symptoms, reproduction steps, and allowed scope.
Establish failure signals that accurately capture the symptoms, trace the real execution path, and investigate other impacts of the same cause and similar code locations.
After the fix is approved, modify the layer where the rule resides, avoiding unrelated refactoring; historical data fixes require separate authorization.
Re-run the original full failure path and affected paths, review the final diff, and report evidence, gaps, and rollback method.

Deliverables

Root cause explanation corresponding to the failure evidence
Actual changes, regression evidence, unverified risks, and rollback explanation

Limitations

Requiring diagnosis does not equal authorization to modify the product.
If unable to reproduce, only a tentative root cause can be given and the evidence gap explained; the fix must still have a valid regression signal.
Questioners may be used as needed; when independent review is missing, it must be stated.

Example Prompts, Not an Actual Execution Case

Use $bug-fixing to diagnose why saving a personal profile shows success, but after refresh it reverts to the old value. Follow the original browser steps and map the request to the read-back result. Do not modify code or historical data; only report the cause, evidence, and fix suggestion.

This guide describes the in-package workflow, does not represent validated cross-model reliability, and is not an actual acceptance run report.

Inside the skill

SKILL.md

---
name: bug-fixing
license: MIT
description: >-
  Reproduce failures, regressions, and data/UI inconsistencies; trace the real execution path to the root cause, make a minimal authorized repair, and verify related paths.
  Scale evidence collection, testing, and challenge to actual risk. Not for new-feature planning or test design alone.
---

# Evidence-Driven Bug Fixing

Find the first boundary on the actual failure path that violates the correct rule. Fix the entire defect class at the layer responsible for that rule, and demonstrate recovery with the original failing input and related paths. Reduce redundant process, not causal evidence or applicable checks.

Do not change product code when only diagnosis was requested. When repair is already authorized, continue within scope without asking again. For a new product decision, expanded scope, changed data/permission/security semantics, or an unauthorized external action, complete independent investigation and a concrete proposal first, then ask only for the missing decision. Check command side effects too. For a growing incident, existing authorization may permit reversible containment while preserving original evidence; containment is not a root-cause fix.

## Select Work for the Actual Situation

Included files · 7

bug-fixing/LICENSE
bug-fixing/MANIFEST.json
bug-fixing/README.md
bug-fixing/SKILL.md
bug-fixing/agents/challenger.md
bug-fixing/agents/openai.yaml
bug-fixing/references/web-data-diagnosis.md