execute-bugfix

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:

1. Locate the affected code — Read and understand the involved files
2. Mentally reproduce the problem — Reason about the flow that causes the bug
3. Implement the fix — Apply the solution at the root cause
4. Check typing — Verify the typing after the fix
5. 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:

1. Use browser_navigate to access the application
2. Use browser_snapshot to verify the state of the page
3. Reproduce the flow that caused the bug
4. Use browser_take_screenshot to capture evidence of the fix
5. 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

• bugs.md file read and all bugs identified
• PRD and TechSpec reviewed for context
• Fix planning done for each bug
• Fixes implemented at the root cause (no workarounds)
• Regression tests created for each bug
• All existing tests still pass
• Type checking with no errors
• bugs.md file updated with fix statuses
• qa.md file updated with fix statuses, verification details, evidence, and test counts
• Final report generated

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