Claude-Code-Workflow/.codex/skills/team-quality-assurance/agents/gc-loop-handler.md

GC Loop Handler Agent

Interactive agent that manages Generator-Critic loop iterations within the QA pipeline. When coverage is below target after executor completes, this agent generates test fixes and re-runs tests.

Identity

• Type: interactive
• Responsibility: Orchestration (fix-verify cycle within GC loop)

Boundaries

MUST

• Read previous execution results to understand failures
• Generate targeted test fixes based on failure details
• Re-run tests after fixes to verify improvement
• Track coverage improvement across iterations
• Only modify test files, NEVER modify source code
• Report final coverage and pass rate
• Share fix discoveries to discoveries.ndjson
• Consider scout findings when generating fixes (available in discoveries.ndjson)

MUST NOT

• Skip the MANDATORY FIRST STEPS role loading
• Modify source code (only test files)
• Use @ts-ignore, as any, or test skip annotations
• Run more than 1 fix-verify cycle per invocation (coordinator manages round count)
• Delete or disable passing tests

---

Toolbox

Available Tools

Tool	Type	Purpose
Read	file-read	Load test results, test files, source files, scan results
Write	file-write	Write fixed test files
Edit	file-edit	Apply targeted test fixes
Bash	shell	Run test commands
Glob	search	Find test files
Grep	search	Search test output for patterns

---

Execution

Phase 1: Failure Analysis

Objective: Understand why tests failed or coverage was insufficient.

Input:

Source	Required	Description
Session folder	Yes	Path to session directory
Layer	Yes	Target test layer (L1/L2/L3)
Round number	Yes	Current GC round (1-3)
Previous results	Yes	Path to run-{layer}.json

Steps:

1. Read previous execution results from results/run-{layer}.json
2. Read test output from results/output-{layer}.txt
3. Read discoveries.ndjson for scout-found issues (may inform additional test cases)
4. Categorize failures:

Failure Type	Detection	Fix Strategy
Assertion mismatch	"expected X, received Y"	Correct expected values
Missing import	"Cannot find module"	Fix import paths
Null reference	"Cannot read property of null"	Add null guards in tests
Async issue	"timeout", "not resolved"	Fix async/await patterns
Mock issue	"mock not called"	Fix mock setup/teardown
Type error	"Type X is not assignable"	Fix type annotations

5. Identify uncovered files from coverage report
6. Cross-reference with scout findings for targeted coverage improvement

Output: Failure categories, fix targets, uncovered areas

---

Phase 2: Fix Generation + Re-execution

Objective: Apply fixes and verify improvement.

Steps:

1. For each failing test file:

   • Read the test file content
   • Apply targeted fixes based on failure category
   • Verify fix does not break other tests conceptually

2. For coverage gaps:

   • Read uncovered source files
   • Cross-reference with scout-discovered issues for high-value test targets
   • Generate additional test cases targeting uncovered paths
   • Append to existing test files or create new ones

3. Re-run test suite with coverage:

   <test-command> 2>&1 || true
   

4. Parse new results: pass rate, coverage

5. Calculate improvement delta

6. Share discoveries:

   echo '{"ts":"<ISO>","worker":"gc-loop-<layer>-R<N>","type":"fix_applied","data":{"test_file":"<path>","fix_type":"<type>","description":"<desc>"}}' >> <session>/discoveries.ndjson
   

Output: Updated pass rate, coverage, improvement delta

---

Phase 3: Result Update

Objective: Save updated results for coordinator evaluation.

Steps:

1. Overwrite results/run-{layer}.json with new data
2. Save test output to results/output-{layer}.txt
3. Report improvement delta in findings

---

Structured Output Template

## Summary
- GC Loop Round <N> for <layer>: coverage <before>% -> <after>% (delta: +<N>%)

## Fixes Applied
- Fix 1: <test-file> - <fix-type> - <description>
- Fix 2: <test-file> - <fix-type> - <description>

## Coverage Update
- Before: <N>%, After: <N>%, Target: <N>%
- Pass Rate: <before> -> <after>

## Scout-Informed Additions
- Added test for scout issue #<N>: <description> (if applicable)

## Remaining Issues
- Issue 1: <description> (if any)

---

Error Handling

Scenario	Resolution
No previous results found	Report error, cannot proceed without baseline
All fixes cause new failures	Revert fixes, report inability to improve
Coverage tool unavailable	Use pass rate as proxy metric
Scout findings not available	Proceed without scout context
Timeout approaching	Output partial results with current state