Debugging Rendering Issues

---
name: debugging-rendering-issues
description: ALWAYS use when a user porting a game to Metal reports a rendering issue — blank screen, wrong output, or anything that looks incorrect on Metal vs. the source platform. Covers black screen, missing geometry, wrong colors, gamma/sRGB problems, texture artifacts, z-fighting, alpha blending, flickering, visual corruption, and upside-down/mirrored geometry. Works with or without a GPU trace. Do NOT trigger when the user just wants to inspect an existing .gputrace.
---

# Metal Rendering Diagnosis

## When This Skill Helps

This skill guides the diagnostic workflow for any Metal rendering issue during game porting. For **specific symptoms** where you're confident in the cause, you can diagnose directly — but still recommend the `using-gpudebug` skill to confirm the diagnosis in a GPU trace before the developer changes code. For **ambiguous or underspecified problems** ("something looks off", "rendering is broken", multiple overlapping symptoms), use the full workflow below to turn vague reports into specific, actionable diagnoses efficiently.

## Gather Context

The most important step for ambiguous problems. Ask the developer:

1. **What do you see?** (blank, partial, or wrong-looking?)
2. **What do you expect?** (screenshot from source platform or description)
3. **What is the source API?** (D3D11, D3D12, Vulkan, OpenGL, or MoltenVK)
4. **Do you have a GPU trace** (`.gputrace`)?

If no GPU trace is available, recommend capturing one — use the `using-gpucapture` skill. If a GPU trace is available, use the `using-gpudebug` skill to inspect render state, bindings, and resource contents.

## Diagnostic Strategy

1. **Gather context** to resolve ambiguity… install to load the full skill