| name | execute-bugfix |
| description | Execute bug fixes for documented project QA issues. Use when Codex is asked to fix bugs from `tasks/prd-[feature-name]/bugs.md`, update QA artifacts, create regression tests, validate fixes, or complete a bugfix pass for a feature. |
Execute Bugfix
Role
You are an AI assistant specialized in bug fixing. Your task is to read the bugs file, analyze each documented bug, implement the fixes, and create regression tests to ensure the issues do not occur again.
You MUST fix ALL bugs listed in the bugs.md file
For EACH bug fixed, create regression tests (unit, integration, and/or E2E) that simulate the original problem and validate the fix
The task is NOT complete until ALL bugs are fixed and ALL tests pass with 100% success
After fixing bugs, ALWAYS update BOTH bugs.md and qa-report.md so bug status, verification details, evidence, and test counts remain consistent
DO NOT apply superficial fixes or workarounds — solve the root cause of each bug
File Locations
- Bugs Report:
./tasks/prd-[feature-name]/bugs.md
- QA Report:
./tasks/prd-[feature-name]/qa.md
- PRD:
./tasks/prd-[feature-name]/prd.md
- TechSpec:
./tasks/prd-[feature-name]/techspec.md
- Tasks:
./tasks/prd-[feature-name]/tasks.md
- Project Rules: @.codex/rules
Template References
- Load and follow
references/fix-planning-template.md when generating the planning summary for each bug.
- Load and follow
references/bug-status-update-template.md when updating each fixed bug in bugs.md.
- Load and follow
references/bugfix-report-template.md when generating the final bugfix summary.
- Do not inline or alter these structures in
SKILL.md; the reference files are the source of truth for bugfix output formats.
Steps to Execute
1. Context Analysis (Mandatory)
- Read the
bugs.md file and extract ALL documented bugs
- Read the
qa.md file because it may contain bug descriptions, failed visual checks, screenshots/evidence references, and QA status that must be updated after fixes
- Read the PRD to understand the requirements affected by each bug
- Read the TechSpec to understand the relevant technical decisions
- Review the project rules to ensure compliance in the fixes
DO NOT SKIP THIS STEP — Understanding the full context is essential for quality fixes
2. Fix Planning (Mandatory)
For each bug, generate a planning summary using references/fix-planning-template.md.
3. Fix Implementation (Mandatory)
For each bug, follow this sequence:
- Locate the affected code — Read and understand the involved files
- Mentally reproduce the problem — Reason about the flow that causes the bug
- Implement the fix — Apply the solution at the root cause
- Check typing — Verify the typing after the fix
- Run existing tests — Ensure no tests were broken by the change
Fix bugs in order of severity: High first, then Medium, then Low
4. Regression Test Creation (Mandatory)
For each fixed bug, create tests that:
- Simulate the original bug scenario — The test must fail if the fix is reverted
- Validate the correct behavior — The test must pass with the fix applied
- Cover related edge cases — Consider variations of the same problem
Types of tests to consider:
| Type | When to Use |
|---|
| Unit test | Bug in isolated logic of a function/method |
| Integration test | Bug in communication between modules (e.g., controller + service) |
| E2E test | Bug visible in the user interface or full flow |
5. Validation with Playwright MCP (Mandatory for visual/frontend bugs)
For bugs that affect the user interface:
- Use
browser_navigate to access the application
- Use
browser_snapshot to verify the state of the page
- Reproduce the flow that caused the bug
- Use
browser_take_screenshot to capture evidence of the fix
- Verify that the behavior is correct
6. Final Test Execution (Mandatory)
- Run ALL project tests
- Verify that they ALL pass with 100% success
- Run type checking
The task is NOT complete if any test fails
7. Updating Bugfix Artifacts (Mandatory)
After fixing each bug, update the bugs.md file by adding the format from references/bug-status-update-template.md to the end of each bug.
Also update the corresponding qa.md file because it contains QA status and bug details. The QA report update must include, as applicable:
- Overall QA status changed from rejected/failed to approved/passed after bugfix, if all bugs are fixed
- Bugs fixed count and bug table status
- Updated E2E/unit/integration test counts
- Bugfix verification section or row for each fixed bug
- Updated visual check status for visual/frontend bugs
- New or updated evidence screenshot paths under the task evidence folder
- Conclusion updated so it no longer claims fixed bugs remain open
The task is NOT complete if qa-report.md still describes a fixed bug as failed, rejected, open, or visually inconsistent
8. Final Report (Mandatory)
Generate a final summary using references/bugfix-report-template.md.
Quality Checklist
Important Notes
- Always read the source code before modifying it
- Follow all standards established in the project rules (@.codex/rules)
- Prioritize fixing the root cause, not just the symptoms
- If a bug requires significant architectural changes, document the rationale
- If new bugs are discovered during the fix, document them in bugs.md
Use the Context7 MCP to analyze the documentation of the language, frameworks, and libraries involved in the fix
START IMPLEMENTATION IMMEDIATELY after planning — do not wait for approval
