Skip to content
Skills Library
Programming · Building & coding

bug-fix-process

/bug-fix-process

Process a known bug ID from a structured bug review into a revalidated fix plan and implementation path, including fix-worthiness, multiple-choice user decisions, architectural/common-pattern analysis, consistency and naming review, TDD regression tests, maintainability improvements, verification, tracker updates, and commit reporting. Use when Codex is given a specific bug ID and asked whether or how to fix it, or asked to proceed from a reviewed bug into a fix.

Licence
AGPL-3.0
Last repository change
20.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Process a known bug ID from a structured bug review into a revalidated fix plan and implementation path, including fix-worthiness, multiple-choice user decisions, architectural/common-pattern analysis, consistency and naming review, TDD regression tests, maintainability improvements, verification, tracker updates, and commit reporting. Use when Codex is given a specific bug ID and asked whether or how to fix it, or asked to proceed from a reviewed bug into a fix.

Original author description

Process a known bug ID from a structured bug review into a revalidated fix plan and implementation path, including fix-worthiness, multiple-choice user decisions, architectural/common-pattern analysis, consistency and naming review, TDD regression tests, maintainability improvements, verification, tracker updates, and commit reporting. Use when Codex is given a specific bug ID and asked whether or how to fix it, or asked to proceed from a reviewed bug into a fix.

How it works

  1. Overview
  2. Intake
  3. Workflow
  4. Fix-Worthiness Assessment
  5. Architecture and Pattern Assessment
  6. Decision Package
  7. TDD Fix Flow
  8. Completion Report
Original SKILL.md headings · 131 lines, 1,104 words
SKILL.md preview
---
name: bug-fix-process
description: Process a known bug ID from a structured bug review into a revalidated fix plan and implementation path, including fix-worthiness, multiple-choice user decisions, architectural/common-pattern analysis, consistency and naming review, TDD regression tests, maintainability improvements, verification, tracker updates, and commit reporting. Use when Codex is given a specific bug ID and asked whether or how to fix it, or asked to proceed from a reviewed bug into a fix.
---

# Bug Fix Process

## Overview

Use this skill after a bug has already been identified or assigned an ID. The goal is to revalidate the specific bug, decide whether it should be fixed now, choose the right fix shape, then implement with tests and verification.

This complements `code-review-process`: that skill finds and validates bugs; this skill processes one reviewed bug ID into a fix decision and, when approved, a verified change.

## Intake

Start from a concrete bug identifier. Accept or infer:

- `bug_id`: e.g. `BUG-001`, `CQ-003`, `SEC-001`, or a project-specific ID.
- `source`: review report, tracker, PR comment, issue, branch notes, or user-provided bug text.
- `fix_mode`: `recommend-only`, `ask-before-fix`, or `fix-approved`.
- `scope`: paths, commits, project entry, PR, issue, or exact files.
- `verification`: `targeted`, `repo-standard`, or `full-gate`.

If the bug ID or source is missing, inspect nearby review artifacts first. If still unclear, ask for the bug ID or paste of the finding before proceeding.

## Workflow

1. Read repo instructions first. Follow local guidance such as `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING`, Makefiles, justfiles, package scripts, and CI configs.
2. Locate the bug record. Preserve the original ID, severity, failing scenario, expected behavior, evidence, proposed regression test, and any prior user decision.
3. Revalidate before planning. Reproduce or source-prove the bug against the current code. Prefer the exact original command or scenario, then a simple direct shell/user-facing form when practical.
4. Restate the bug precisely: what fails, what works, which inputs/files/config/output mode matter, and whether this is a base-case failure, edge-case failure, output-format failure, environment-specific failure, or unclear contract.
5. Run the fix-worthiness assessment.
6. Run the architecture and common-pattern assessment.
7. Present a decision package. Use a multiple-choice user-input tool when available; otherwise show concise numbered options and ask for a choice.
8. If approved, write the regression test first and run it to see the expected failure where practical.
9. Implement the chosen fix shape.
10. Run the targeted regression test, then widen to the repo-standard verification requested or documented.
11. Update the relevant tracker, project file, or review report when the repo convention or bug source requires it.
12. Commit only when authorized. Use a conventional commit message if the repo requires it and include the bug ID when useful.
13. Finish with the bug ID, selected strategy, files changed, regression test, verification results, tracker status, commit hash or reason no commit was made, and residual risk.

## Fix-Worthiness Assessment

Decide whether the bug is worth fixing now before designing the patch. Evaluate:

- User impact: severity, frequency, affected workflow, data loss, broken output contract, or blocked release.
- Confidence: reproduced, source-proven, flaky, environment-specific, or still ambiguous.
- Workaround: available, documented, acceptable, or unsafe.
- Fix cost: small localized patch, moderate cross-module change, broad refactor, or unclear.
- Regression risk: public API/CLI change, data migration, format change, concurrency risk, or low-risk internal fix.
- Timing: urgent, should batch with related fixes, should save as a project, or not worth fixing.

Recommended outcomes:

- Fix now when impact is real, evidence is strong, and the patch is reasonably bounded.
- Defer when impact is low, workaround is acceptable, or risk exceeds near-term value.
- Reject when revalidation disproves the bug or the expected behavior is not intended.
- Clarify first when product/docs/tests disagree about the intended contract.
- Save as a project when the right fix is architectural and too broad for the current bug.

## Architecture and Pattern Assessment

Before choosing the implementation, check whether the bug is a symptom of a broader pattern.

Look for:

- Duplicated logic across multiple files or commands.
- Existing helpers, abstractions, validators, serializers, adapters, or command patterns that this code failed to use.
- Naming convention drift, inconsistent option names, mismatched method names, or ambiguous terminology.
- Inconsistent error handling, output envelopes, state transitions, config resolution, parsing, or persistence behavior.
- Similar tests that should be mirrored or generalized.
- Code that could become simpler by using the repo's established pattern.

Choose the smallest fix that also improves maintainability when the evidence supports it:

- Minimal targeted fix: use when the bug is isolated and there is no repeated pattern.
- Pattern-aligned fix: use when a local site drifted from an existing convention.
- Shared abstraction: use when the same behavior is duplicated enough that fixing one site leaves likely future bugs.
- Architecture project: use when a better design is real but too broad for the current bug's risk or timeline.

Do not refactor for aesthetics alone. Tie architecture work to bug prevention, consistency, reduced duplication, clearer naming, or simpler future maintenance.

## Decision Package

Before changing code, present the user with a concise decision package unless `fix_mode` is clearly `fix-approved`.

Include:

- Bug ID and current validation status.
- Precise bug scope and known-working scenarios.
- Fix-worthiness recommendation.
- Architecture/common-pattern finding.
- Recommended regression test.
- Recommended fix option.
- Verification plan.

Offer choices such as:

1. Fix now with the minimal targeted patch.
2. Fix now with a pattern-aligned patch using the existing convention.
3. Fix now with a shared abstraction/refactor because the duplicated pattern is the root cause.
4. Clarify expected behavior before fixing.
5. Defer or reject this bug.
6. Save the architectural work as a separate project and only apply the narrow fix, or no fix now.

If multiple-choice tooling is available, use it for these options. Otherwise, ask the user to choose by number.

## TDD Fix Flow

After approval:

1. State the regression test that should fail before the fix.
2. Add or update that test first where practical.
3. Run the test and record the red result. If the bug cannot be captured directly, explain why and use the closest practical guard.
4. Implement the selected fix shape without unrelated cleanup.
5. Run the regression test and record the green result.
6. Run nearby affected tests.
7. Run the repo-standard verification gate or the user-approved substitute.
8. If a wider architectural fix was selected, verify every touched path that now uses the shared pattern.

## Completion Report

Finish with:

- Bug ID and final status.
- Fix decision: minimal, pattern-aligned, shared abstraction, deferred, rejected, clarified, or saved as project.
- Why the selected approach was worth it.
- Regression test and verification commands with results.
- Architecture/pattern changes made or intentionally not made.
- Tracker/report updates.
- Commit hash, or explicit reason no commit was created.
- Residual risk and follow-up project, if any.

Do not claim the bug is fixed unless the regression test or documented substitute exists, verification has run, and the report preserves the exact bug ID and selected fix strategy.
Files in this package (2)
  • SKILL.md 8 KB
  • agents/openai.yaml 1 KB

Versions

The database has no other skills named bug-fix-process.

Database snapshot: 13.11.2026 · package version 63c114871ea2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100fix-bug
    Use when the user asks to fix a known bug, after a regression trace or from a clear report. Triggers include "fix this bug", "patch this", "apply the fix", "repair this crash", "the tracer found the commit, fix it", "make the failing test pass".
  • 100code-review-process
    Structured multi-method process for reviewing code changes for bugs and maintainability risks, including test-suite evaluation, feature-specific probes, design-doc scope review, precise bug scope language, wrapper-aware validation, candidate validation with evidence, contract…
  • 100tdd-fix
    Use when fixing a bug test-first: write a failing test to reproduce it, find the root cause, fix, and add a regression test.
  • 100bug-fix
    Bug fix workflow. Use when: fixing bugs, resolving issues, regression fixes. Not for: new features (use feature-dev), understanding code (use code-explore). Output: fix + regression test + review gate.
  • 100eng-tdd
    Fix a bug test-first when there is a clear, cheap regression test path. Use when the user asks for TDD, a failing test, or a regression test, or when the bug has an obvious cheap local test target.
  • 90triage-issue
    Triage a bug or issue by exploring the codebase to find root cause, then create a GitHub issue with a TDD-based fix plan. Use when user reports a bug, wants to file an issue, mentions "triage", or wants to investigate and plan a fix for a problem.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.