diagnosing-visual-defects
Finds the cause of something wrong on screen in a real-time renderer, such as a band, a seam, specks, a flicker, a dark patch, a halo or something that vanishes for a frame, by turning parts off one at a time and bisecting before any code is changed. Reproduces the defect in the cheapest still view, records its fingerprint, ablates the parts that draw there until it finds the one that causes the defect, confirms it with a sweep of that part's parameter, checks the suspect quantity against a physical or published range, judges temporal defects on clips against a many-sample reference, and then fixes the cause at its source. Use with three.js WebGPU renderers, or any real-time renderer, whenever the cause of a visible artefact is not yet known. It hands nondeterministic frames (the same inputs giving different pixels) to diagnosing-nondeterministic-frames, and images that are technically correct but look wrong to building-cinematic-stylised-realism.
HuberyLL · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add HuberyLL/ponlai --skill diagnosing-visual-defectsAbout this skill
name: diagnosing-visual-defects description: Finds the cause of something wrong on screen in a real-time renderer, such as a band, a seam, specks, a flicker, a dark patch, a halo or something that vanishes for a frame, by turning parts off one at a time and bisecting before any code is changed. Reproduces the defect in the cheapest still view, records its fingerprint, ablates the parts that draw there until it finds the one that causes the defect, confirms it with a sweep of that part's parameter, checks the suspect quantity against a physical or published range, judges temporal defects on clips against a many-sample reference, and then fixes the cause at its source. Use with three.js WebGPU renderers, or any real-time renderer, whenever the cause of a visible artefact is not yet known. It hands nondeterministic frames (the same inputs giving different pixels) to diagnosing-nondeterministic-frames, and images that are technically correct but look wrong to building-cinematic-stylised-realism.
Diagnosing visual defects
Something on screen is wrong and its cause is not known. Reading the code and guessing gives a plausible story and a fix that moves the defect elsewhere. This skill finds the part that causes the defect by experiment, confirms it, and only then changes code.
Rules most often broken without notice
- Measure before you change anything. Do not edit the code under suspicion until an experiment names the part that causes the defect. In one recorded case, an effect took four versions of its design before it was right.
- Turn parts off one at a time on the same view. Read each result with numbers on the same box (a difference, region statistics, a clip metric), not by eye alone.
- One part whose removal removes the defect is a suspect, not a cause. Confirm it with a sweep: move the suspect's parameter and check that the defect follows as the cause predicts.
- Check the suspect quantity against what is physically possible or published (a slope, an albedo, a ratio). A value outside the real range is often the cause behind a symptom.
- Fix the cause where it arises. A clamp, a blur, a threshold or a rule wrapped around the outside hides the cause, and the defect comes back. One recorded case is such a workaround: the project's own sleep rule wrapped around a physics engine's.
- Judge a temporal defect (flicker, shimmer, ghosting, a one-frame drop) on a clip of frames against a many-sample reference of the same motion, never on stills. Judge it on the whole frame as well as on crops.
- If the same inputs give different pixels between runs, stop and use
diagnosing-nondeterministic-frames. If the image is technically correct but looks wrong (too dark, flat, a colour cast), usebuilding-cinematic-stylised-realism.
The project's facts: the binding
Steps marked "(binding: X)" need facts about the project: how to open a still view, how to turn its
parts off, its capture, probe and clip tools, its earlier defects, and where findings are written.
When you reach the step, read section X of docs/bindings/diagnosing-visual-defects.md. If the
project's AGENTS.md or CLAUDE.md names another file for this skill, that file wins.
If there is no binding, find each fact in the project (debug switches and URL options, the debug
handle on window, its screenshot and image-diff tools) and ask the user for what you cannot find.
When the diagnosis ends, offer to write what you found as the binding, one section per step.
Workflow
Copy this checklist and keep it up to date:
- [ ] 1. Describe and reproduce
- [ ] 2. Record the fingerprint
- [ ] 3. Ablate
- [ ] 4. Confirm with a sweep
- [ ] 5. Check the range
- [ ] 6. Fix at the source and compare
- [ ] 7. Record
1. Describe and reproduce (binding: Reproduce)
- Describe the defect in one sentence, in terms of what is on screen: what it is, where it is, under which lighting, weather, hour and view, and whether it is still or moving.
- Reproduce it in the cheapest view that shows it: the smallest test scene if the defect shows there, one camera, and the project's still or test mode for a still defect. Capture it. This capture is the "before" that every later capture is compared with.
- Capture the same view twice from fresh loads. If the two captures differ where the defect is, the
frame is nondeterministic: hand over to
diagnosing-nondeterministic-frames. - If the defect came with a recent change, bisect the commits with this one capture before you ablate, and read the change that brought it.
2. Record the fingerprint (binding: Earlier defects)
Before any guess, measure and write down:
- where: the material or object, the screen region, the distance, the angle to the sun, the height above water or ground, and a box around the defect for every later reading;
- its shape: a band along a height or an angle, a seam on a grid or along tile or chunk borders, single-pixel specks, a halo along edges, a patch, a flicker;
- when: which hours and weathers, after a resize or a render-scale step, on the first frame, only in motion;
- how much: the largest difference and the pixel count against a frame without the defect, or the region's statistics.
Then compare the fingerprint with the project's earlier defects, and check a match first. Past cases have tied these shapes to causes:
| Fingerprint | Suspect first |
|---|---|
| A band along an elevation or angle, sharp-edged | A gate or threshold, or a term counted twice where two models overlap |
| Specks or crumbs over a textured surface seen through another | A slope or normal steeper than real; a texture read at one point where the pixel covers many |
| A few pixels along an edge that change with unrelated edits | Derivatives or implicit samples in a branch (writing-tsl-and-passes) |
| Something vanishes for one frame after a resize or render-scale step | A target re-created and cleared before a pass that |