execute-bugfix

name	execute-bugfix
description	Fix documented QA bugs for a feature by reading bugs.md, qa.md, PRD, Tech Spec, and tasks; planning fixes by severity; implementing root-cause fixes; adding regression tests; validating with project tests and Playwright for UI bugs; and updating bugfix artifacts. Use when Codex is asked to fix bugs, resolve QA findings, address failed QA, or complete bugfix work in tasks/prd-[feature-name]/.

Execute Bugfix

Use this skill to resolve documented feature bugs, add regression coverage, and update QA artifacts.

Required Workflow

1. Analyze context.

   • Identify the feature folder under tasks/prd-[feature-name]/.
   • Read bugs.md and extract all documented bugs.
   • Read qa.md for failed checks, visual evidence, screenshots, and QA status that must be updated.
   • Read prd.md, techspec.md, and tasks.md.
   • Read applicable project rules under .codex/rules/.
   • Read relevant source code before modifying it.

2. Research technical dependencies.

   • Use Context7 MCP for documentation about involved languages, frameworks, libraries, APIs, and patterns when applicable.
   • Prefer official documentation and existing project patterns.

3. Plan fixes.

   • Sort bugs by severity: High, then Medium, then Low.
   • For each bug, produce a planning summary using references/bugfix-planning-template.md.
   • Identify root cause, affected component, files to modify, fix strategy, and planned regression tests.

4. Implement fixes.

   • Start implementation immediately after planning.
   • Fix bugs at the root cause.
   • Avoid symptom-only workarounds.
   • Keep changes scoped to documented bugs.
   • If a fix requires significant architectural change, document the rationale.

5. Create regression tests.

   • For each fixed bug, add tests that fail if the fix is reverted.
   • Use unit tests for isolated logic.
   • Use integration tests for module/API interactions.
   • Use E2E tests for user-visible or full-flow bugs.
   • Cover relevant edge cases.

6. Validate visual or frontend bugs with Playwright MCP.

   • Use browser_navigate to access the app.
   • Use browser_snapshot to verify page state before interaction.
   • Reproduce the original bug flow.
   • Use browser_take_screenshot to capture evidence of the fix.
   • Verify the corrected behavior.

7. Run final verification.

   • Run all relevant project tests.
   • Run type checking.
   • Run lint/build commands when required by project standards.
   • The task is not complete while any required test fails.

8. Update artifacts.

   • Update each fixed bug in bugs.md using references/bug-status-update-template.md.
   • Update qa.md so fixed bugs are not still described as failed, rejected, open, or visually inconsistent.
   • Update QA status to approved/passed only when all bugs are fixed and all required checks pass.
   • Update bug counts, test counts, visual check status, evidence paths, and conclusion as applicable.
   • Document newly discovered bugs in bugs.md.

9. Report results.

   • Use references/bugfix-report-template.md for the final summary.
   • Include changed files, tests run, artifact updates, and any remaining risks.

Hard Rules

• Do not skip reading bugs.md, qa.md, prd.md, techspec.md, and tasks.md.
• Fix bugs in severity order: High first, then Medium, then Low.
• Start implementation immediately after planning.
• Use Context7 MCP for relevant technical documentation when the fix involves frameworks, libraries, or APIs.
• Create regression tests for every fixed bug.
• Validate visual/frontend bugs with Playwright MCP.
• Do not mark the work complete while required tests fail.
• Do not leave qa.md describing fixed bugs as failed, rejected, open, or visually inconsistent.

Quality Checklist

• bugs.md was read and all bugs were identified.
• qa.md, PRD, Tech Spec, and tasks were reviewed.
• Applicable .codex/rules/ entries were checked.
• Fix planning was completed for each bug.
• Fixes were implemented at the root cause.
• Regression tests were created for each bug.
• Visual/frontend bugs were verified with Playwright MCP.
• Existing and new tests pass.
• Type checking has no errors.
• bugs.md was updated with fixed statuses.
• qa.md was updated with fix statuses, verification details, evidence, and test counts.
• Final bugfix report was provided.