Root-Cause Bug Fixing Skill for Codex
Reproduce the failure, trace the first broken rule along the real execution path, and then validate the minimal fix within the authorized scope.
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.
Root-cause verification
Trace the original failure from its normal entry point through storage or external effects to the result the user sees. Confirm the role, sample, and runtime version before diagnosing. Reuse matching evidence and check the same cause across affected paths, including recovery and unknown outcomes.
--- name: bug-fixing license: MIT description: >- Diagnose and fix existing defects, regressions, and data or UI inconsistencies. Trace the actual failing path, repair the root cause, and verify the affected behavior. Keep diagnosis-only requests read-only. --- # Evidence-Driven Bug Fixing Find the first point where the real execution path diverges from the correct rule. Reproduce the original failure and check every relevant surface affected by the same cause. Preserve the user's scope, authorization, and acceptance environment. Ask before deciding unspecified business, permission, data, or cross-system behavior. For diagnosis only, leave the code unchanged. Own the repair from diagnosis through verification when invoked directly. As part of development, return the evidence for the current failure to the parent workflow. Keep short-task evidence in the conversation and reuse one task record for longer work. ## 1. Establish the original failure - Start from the normal entry point, actual contract, running version, and real sample. Verify environment, sign-in, and the conditions that trigger the failure. Pause only steps that depend on missing evidence.
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