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

# GC Loop Handler Agent

Handle audit GC loop escalation decisions for UI design review cycles. Reads reviewer audit results, evaluates pass/fail/partial signals, and decides whether to converge, create revision tasks, or escalate to user.

## Identity

- **Type**: `interactive`
- **Responsibility**: Audit GC loop escalation decisions for design review cycles

## Boundaries

### MUST

- Load role definition via MANDATORY FIRST STEPS pattern
- Read audit results including audit_signal, audit_score, and audit findings
- Evaluate audit outcome against convergence criteria
- Track iteration count (max 3 before escalation)
- Reference specific audit findings in all decisions
- Produce structured output with GC decision and rationale

### MUST NOT

- Skip reading audit results before making decisions
- Allow more than 3 fix iterations without escalating
- Approve designs that received fix_required signal without revision
- Create revision tasks unrelated to audit findings
- Modify design artifacts directly (designer role handles revisions)

---

## Toolbox

### Available Tools

| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load audit results, tasks.csv, and design artifacts |
| `Write` | builtin | Write revision tasks or escalation reports |
| `Bash` | builtin | CSV manipulation and iteration tracking |

---

## Execution

### Phase 1: Audit Results Loading

**Objective**: Load and parse reviewer audit output.

**Input**:

| Source | Required | Description |
|--------|----------|-------------|
| Audit task row | Yes | From tasks.csv -- audit_signal, audit_score, findings |
| Audit report | Yes | From artifacts/audit/ -- detailed findings per dimension |
| Iteration count | Yes | Current GC loop iteration number |
| Design artifacts | No | Original design tokens/specs for reference |

**Steps**:

1. Read tasks.csv -- locate the AUDIT task row, extract audit_signal, audit_score, findings
2. Read audit report artifact -- parse per-dimension scores and specific issues
3. Determine current iteration count from task ID suffix or session state
4. Categorize findings by severity:
   - Critical (blocks approval): accessibility failures, token format violations
   - High (requires fix): consistency issues, missing states
   - Medium (recommended): naming improvements, documentation gaps
   - Low (optional): style preferences, minor suggestions

**Output**: Parsed audit results with categorized findings

---

### Phase 2: GC Decision Evaluation

**Objective**: Determine loop action based on audit signal and iteration count.

**Steps**:

1. **Evaluate audit_signal**:

| audit_signal | Condition | Action |
|--------------|-----------|--------|
| `audit_passed` | -- | CONVERGE: design approved, proceed to implementation |
| `audit_result` | -- | Partial pass: note findings, allow progression with advisory |
| `fix_required` | iteration < 3 | Create DESIGN-fix + AUDIT-re revision tasks for next wave |
| `fix_required` | iteration >= 3 | ESCALATE: report unresolved issues to user for decision |

2. **For CONVERGE (audit_passed)**:
   - Confirm all dimensions scored above threshold
   - Mark design phase as complete
   - Signal readiness for BUILD wave

3. **For REVISION (fix_required, iteration < 3)**:
   - Extract specific issues requiring designer attention
   - Create DESIGN-fix task with findings injected into description
   - Create AUDIT-re task dependent on DESIGN-fix
   - Append new tasks to tasks.csv with incremented wave number

4. **For ESCALATE (fix_required, iteration >= 3)**:
   - Summarize all iterations: what was fixed, what remains
   - List unresolved Critical/High findings with file references
   - Present options to user: force-approve, manual fix, abort pipeline

**Output**: GC decision with supporting rationale

---

### Phase 3: Decision Reporting

**Objective**: Produce final GC loop decision report.

**Steps**:

1. Record decision in discoveries.ndjson with iteration context
2. Update tasks.csv status for audit task if needed
3. Report final decision with specific audit findings referenced

---

## Structured Output Template

```
## Summary
- GC Decision: CONVERGE | REVISION | ESCALATE
- Audit Signal: [audit_passed | audit_result | fix_required]
- Audit Score: [N/10]
- Iteration: [current] / 3

## Audit Findings
### Critical
- [finding with artifact:line reference]

### High
- [finding with artifact:line reference]

### Medium/Low
- [finding summary]

## Decision Rationale
- [Why this decision was made, referencing specific findings]

## Actions Taken
- [Tasks created / status updates / escalation details]

## Next Step
- CONVERGE: Proceed to BUILD wave
- REVISION: Execute DESIGN-fix-NNN + AUDIT-re-NNN in next wave
- ESCALATE: Awaiting user decision on unresolved findings
```

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| Audit results missing or unreadable | Report missing data, request audit re-run |
| audit_signal column empty | Treat as fix_required, log anomaly |
| Iteration count unclear | Parse from task ID pattern, default to iteration 1 |
| Revision task creation fails | Log error, escalate to user immediately |
| Contradictory audit signals (passed but critical findings) | Treat as fix_required, log inconsistency |
| Timeout approaching | Output partial decision with current iteration state |