# Bug Fixing

> Reproduces, diagnoses, fixes, and validates a concrete software defect with the smallest safe change and regression protection. Use when a bug report, failing test, regression, crash, or incorrect behavior requires corrective engineering work.

- Skill: `egohygiene/bug-fixing` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add egohygiene/bug-fixing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egohygiene/bug-fixing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: egohygiene (https://skillmd.com/u/egohygiene)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egohygiene/bug-fixing

---


# Bug Fixing

<!-- aether-continuity-disposition: reader-writer -->

## Repository continuity composition

For repository-scoped work, compose `maintain-repository-continuity` in
**Resume** mode before selecting work. After an authorized repository change
passes domain validation, compose **Refresh** and **Verify** immediately before
presenting the pull request, and include the reconciled root `CONTINUITY.md` in
the same change. A policy-permitted no-change or exemption result must be
documented instead of fabricating an edit.

- **Contribute:** Reproduction signal, root cause, bounded fix, regression protection, validation, and residual risk
- **Never claim:** That a defect is fixed, reviewed, or merged without the corresponding evidence

## Purpose

Execute a bounded defect-correction workflow from reproduction through focused
validation while preserving behavior outside the broken invariant.

## Required Inputs

Resolve as much of the following as possible:

- observed behavior, expected behavior, and failure evidence
- reproduction steps, environment, and scope
- affected code paths, tests, and recent relevant changes
- validation commands and repository constraints
- authorization boundaries, especially when diagnosis-only work was requested

Label missing reproduction evidence instead of masking it.

## Workflow

1. establish the failure and reproduce it when feasible
2. diagnose the root cause without confusing symptoms for the underlying defect
3. choose the smallest safe correction that restores the intended invariant
4. add or update regression protection using:

    - `./references/regression-checklist.md`
    - `./templates/BUG_FIX_REPORT.template.md`

5. validate the focused fix with targeted tests and required broader checks
6. report reproduction evidence, root cause, the exact fix, residual risk, and any checks that could not run

## Constraints

- Do not implement changes during a diagnosis-only request.
- Do not suppress errors, remove safeguards, or weaken tests merely to pass validation.
- Do not broaden the change set into unrelated refactors.
- Do not claim a bug is fixed without evidence from focused validation.
- Do not hide missing reproduction steps or ambiguous evidence.

## Completion Criteria

- [ ] Reproduction or the strongest available proxy signal is explicit.
- [ ] The root cause is distinguished from symptoms.
- [ ] The code change is minimal and behavior-preserving outside the defect.
- [ ] Regression protection covers the broken behavior.
- [ ] Validation results and residual risk are reported truthfully.

## Provenance

This canonical skill is first-party Ego Hygiene content curated from the staged
candidate at `.staging/skills/bug-fixing/SKILL.md`.

## Source Delta

- Adopted: the staged reproduce -> diagnose -> minimal fix -> regression test
  -> validate workflow and the explicit warning against unrelated refactors.
- Rewritten: canonical metadata, regression-focused resources, diagnosis-only
  authorization handling, and deterministic eval coverage.
- Rejected: the narrower `diagnose` overlap as a separate canonical identity for
  this issue; diagnosis remains part of this workflow but must stay separate when
  the request does not authorize implementation.