BMAD-METHOD/expansion-packs/bmad-godot-game-dev/tasks/apply-qa-fixes.md

<!-- Powered by BMAD™ Core -->

# apply-qa-fixes

Implement fixes based on QA results (gate and assessments) for a specific Godot game story. This task is for the Game Developer agent to systematically consume QA outputs and apply game code/test changes while only updating allowed sections in the story file.

## Purpose

- Read QA outputs for a game story (gate YAML + assessment markdowns)
- Create a prioritized, deterministic fix plan for game features
- Apply game code and test changes to close gaps and address issues
- Update only the allowed story sections for the Game Developer agent

## Inputs

```yaml
required:
  - story_id: '{epic}.{story}' # e.g., "2.2"
  - qa_root: from `.bmad-godot-game-dev/config.yaml` key `qa.qaLocation` (e.g., `docs/project/qa`)
  - story_root: from `.bmad-godot-game-dev/config.yaml` key `devStoryLocation` (e.g., `docs/project/stories`)
  - project_root: Godot project root directory (containing project.godot)

optional:
  - story_title: '{title}' # derive from story H1 if missing
  - story_slug: '{slug}' # derive from title (lowercase, hyphenated) if missing
```

## QA Sources to Read

- Gate (YAML): `{qa_root}/gates/{epic}.{story}-*.yml`
  - If multiple, use the most recent by modified time
- Assessments (Markdown):
  - Test Design: `{qa_root}/assessments/{epic}.{story}-test-design-*.md`
  - Traceability: `{qa_root}/assessments/{epic}.{story}-trace-*.md`
  - Risk Profile: `{qa_root}/assessments/{epic}.{story}-risk-*.md`
  - NFR Assessment: `{qa_root}/assessments/{epic}.{story}-nfr-*.md`

## Prerequisites

- Godot 4.x installed and configured
- Testing frameworks installed:
  - **GDScript**: GUT (Godot Unit Test) framework installed as addon
  - **C#**: GoDotTest or GodotTestDriver NuGet packages installed
- Project builds successfully in Godot Editor
- Test commands available:
  - GDScript: `godot --headless --script res://addons/gut/gut_cmdln.gd`
  - C#: `dotnet test` or `godot --headless --run-tests`

## Process (Do not skip steps)

### 0) Load Core Config & Locate Story

- Read `.bmad-core/core-config.yaml` and resolve `qa_root`, `story_root`, and `project_root`
- Locate story file in `{story_root}/{epic}.{story}.*.md`
  - HALT if missing and ask for correct story id/path

### 1) Collect QA Findings

- Parse the latest gate YAML:
  - `gate` (PASS|CONCERNS|FAIL|WAIVED)
  - `top_issues[]` with `id`, `severity`, `finding`, `suggested_action`
  - `nfr_validation.*.status` and notes
  - `trace` coverage summary/gaps
  - `test_design.coverage_gaps[]`
  - `risk_summary.recommendations.must_fix[]` (if present)
- Read any present assessment markdowns and extract explicit gaps/recommendations

### 2) Build Deterministic Fix Plan (Priority Order)

Apply in order, highest priority first:

1. High severity items in `top_issues` (gameplay/performance/stability/maintainability)
2. NFR statuses: all FAIL must be fixed → then CONCERNS
3. Test Design `coverage_gaps` (prioritize P0 gameplay scenarios)
4. Trace uncovered requirements (AC-level, especially gameplay mechanics)
5. Risk `must_fix` recommendations
6. Medium severity issues, then low

Guidance:

- Prefer tests closing coverage gaps before/with code changes
- Keep changes minimal and targeted; follow Godot best practices and project architecture
- Respect scene organization and node hierarchy
- Follow GDScript style guide or C# conventions as appropriate

### 3) Apply Changes

- Implement game code fixes per plan:
  - GDScript: Follow Godot style guide, use signals for decoupling
  - C#: Follow .NET conventions, use events/delegates appropriately
- Add missing tests to close coverage gaps:
  - **GDScript Tests (GUT)**:
    - Unit tests in `test/unit/` for game logic
    - Integration tests in `test/integration/` for scene interactions
    - Use `gut.p()` for parameterized tests
    - Mock nodes with `double()` and `stub()`
  - **C# Tests (GoDotTest/GodotTestDriver)**:
    - Unit tests using xUnit or NUnit patterns
    - Integration tests for scene and node interactions
    - Use test fixtures for game state setup
- Follow Godot patterns:
  - Autoload/singleton patterns for global game state
  - Signal-based communication between nodes
  - Resource files (.tres/.res) for data management
  - Scene inheritance for reusable components

### 4) Validate

**For GDScript Projects:**

- Run GUT tests: `godot --headless --script res://addons/gut/gut_cmdln.gd -gselect=test/ -gexit`
- Check for script errors in Godot Editor (Script Editor panel)
- Validate scene references and node paths
- Run game in editor to verify no runtime errors

**For C# Projects:**

- Build solution: `dotnet build`
- Run tests: `dotnet test` or `godot --headless --run-tests`
- Check for compilation errors
- Validate no null reference exceptions in gameplay

**For Both:**

- Test gameplay mechanics manually if needed
- Verify performance (check FPS, memory usage)
- Iterate until all tests pass and no errors

### 5) Update Story (Allowed Sections ONLY)

CRITICAL: Dev agent is ONLY authorized to update these sections of the story file. Do not modify any other sections (e.g., QA Results, Story, Acceptance Criteria, Dev Notes, Testing):

- Tasks / Subtasks Checkboxes (mark any fix subtask you added as done)
- Dev Agent Record →
  - Agent Model Used (if changed)
  - Debug Log References (test results, Godot console output)
  - Completion Notes List (what changed, why, how)
  - File List (all added/modified/deleted files)
- Change Log (new dated entry describing applied fixes)
- Status (see Rule below)

Status Rule:

- If gate was PASS and all identified gaps are closed → set `Status: Ready for Done`
- Otherwise → set `Status: Ready for Review` and notify QA to re-run the review

### 6) Do NOT Edit Gate Files

- Dev does not modify gate YAML. If fixes address issues, request QA to re-run `review-story` to update the gate

## Blocking Conditions

- Missing `.bmad-core/core-config.yaml`
- Story file not found for `story_id`
- No QA artifacts found (neither gate nor assessments)
  - HALT and request QA to generate at least a gate file (or proceed only with clear developer-provided fix list)
- Godot project file (`project.godot`) not found
- Testing framework not properly installed (GUT addon missing or NuGet packages not restored)

## Completion Checklist

- Godot project builds without errors
- All tests pass:
  - GDScript: GUT tests green
  - C#: dotnet test successful
- No script errors in Godot Editor
- All high severity `top_issues` addressed
- NFR FAIL → resolved; CONCERNS minimized or documented
- Coverage gaps closed or explicitly documented with rationale
- Gameplay features tested and working
- Story updated (allowed sections only) including File List and Change Log
- Status set according to Status Rule

## Example: Story 2.2 - Player Movement System

Given gate `docs/project/qa/gates/2.2-*.yml` shows

- `coverage_gaps`: Jump mechanics edge cases untested (AC2)
- `coverage_gaps`: Input buffering not tested (AC4)
- `top_issues`: Performance drops when multiple players active

Fix plan:

**GDScript Example:**

- Add GUT test for jump height variation based on button hold time
- Add test for input buffering during state transitions
- Optimize player movement script using object pooling for effects
- Test with `gut.p()` parameterized tests for different player counts

**C# Example:**

- Add GoDotTest unit test for jump physics calculations
- Add integration test for input system using GodotTestDriver
- Refactor movement system to use Jobs/Tasks for parallel processing
- Verify with performance profiler

- Re-run tests and update Dev Agent Record + File List accordingly

## Key Principles

- Deterministic, risk-first prioritization
- Minimal, maintainable changes following Godot best practices
- Tests validate gameplay behavior and close gapså
- Respect Godot's node-based architecture and signal system
- Maintain clear separation between game logic and presentation
- Strict adherence to allowed story update areas
- Gate ownership remains with QA; Game Developer signals readiness via Status

## Testing Framework References

### GUT (GDScript)

- Documentation: https://github.com/bitwes/Gut/wiki
- Test structure: `extends GutTest`
- Assertions: `assert_eq()`, `assert_true()`, `assert_has_signal()`
- Mocking: `double()`, `stub()`, `spy_on()`

### GoDotTest/GodotTestDriver (C#)

- GoDotTest: xUnit-style testing for Godot C#
- GodotTestDriver: Integration testing with scene manipulation
- Test attributes: `[Fact]`, `[Theory]`, `[InlineData]`
- Scene testing: Load scenes, interact with nodes, verify state