Primary target surface
This non-rendering suite is generated from canonical fixtures. Acceptance comes from deterministic route verdicts and negative controls, not GPU readback.
Three.js Debugging
Diagnose unexpected Three.js WebGPU/TSL runtime, rendering, API, asset, or version behavior. Use for a concrete failure, a suspected upstream regression or known issue, or a choice among an application fix, released upgrade, bounded workaround, upstream report, and blocker.
Image: Deterministic contract-lab screenshot. Source lab: debugging-contract-lab.
Evidence reports
Source hashes, claim verdicts, promoted same-lab media, fixed routes, exact tier contracts, and current limitations.
Accepted primary labs
Only schema-v2 labs with accepted runtime and evidence contracts appear here. Other source directories remain visible through the demo registry without being promoted to runnable proof.
Preview and evidence ledger
Every image identifies what it proves. This skill owns a non-rendering scenario suite, so acceptance depends on deterministic fixture verdicts, ownership and budget checks, and mutations rather than GPU pixels.
Accepted runtime evidence available
1 published image
The full skill
The complete SKILL.md as loaded by agents, rendered verbatim.
Three.js Debugging
Reproduce first. Treat installed source and official history as evidence, not as
background trivia. A domain skill defines the intended mechanism;
$threejs-visual-validation supplies formal image, timing, resource, or
regression proof when the diagnosis needs it.
Keep one case record with the symptom, expected behavior, exact environment, minimal reproduction, first failed contract, local evidence, upstream candidates, constant version matrix, conclusion, action, and limits. Record unknown values as unknown.
1. Reproduce the exact environment
Record the resolved package version, runtime THREE.REVISION, lockfile
resolution, import entrypoints, renderer class, initialized backend,
browser/OS/GPU, relevant capabilities, seed, asset revisions, and exact command
or interaction. Build the smallest deterministic reproduction that still fails.
Canonical conclusions require an initialized WebGPURenderer with
renderer.backend.isWebGPUBackend === true. Otherwise record the canonical
blocker; reach $threejs-compatibility-fallbacks only when the user explicitly
requests that branch.
This step is complete when backend truth is recorded, the reproduction fails repeatedly under the recorded environment, and another run can distinguish reproduced from not reproduced.
2. Name the violated contract and first failure
Separate API semantics, numerical invariants, render-state invariants, resource transitions, and visual expectations. Identify the earliest failing assertion, frame, pass, draw, dispatch, resource transition, or diagnostic—not merely the final symptom.
This step is complete when one observable boundary divides the last known-good state from the first bad state.
3. Minimize without replacing the mechanism
Remove unrelated systems while preserving the suspect API, material, geometry path, backend, projection, precision, ownership, and lifecycle behavior. At a cross-system boundary preserve the same units, frames/origin, owner, interval/cadence/sample phase, state identity, validity/staleness/error, reset, and completion semantics.
A different renderer, material, or representation may localize the fault; it cannot prove the original path correct.
This step is complete when every remaining component participates in the first failure and the suspected mechanism is still the one under test.
4. Resolve local evidence
Inspect the installed export map, source, types, tests, examples, and migration material for the resolved revision. Test local hypotheses first: application misuse, stale or duplicate imports, migration changes, missing renderer initialization, unsupported backend/capability, invalid data, duplicate output conversion, lifecycle/synchronization error, and third-party integration.
This step is complete when each plausible local hypothesis has an executable result or an explicit missing-evidence record.
5. Research upstream conditionally
Research upstream only when local evidence does not settle the cause, installed source and current documentation disagree, a version-dependent regression or upgrade is plausible, or the user asks about known issues. Read upstream research before searching and follow its primary-source order.
Classify every candidate independently:
| Classification | Required proof |
|---|---|
usage-or-integration-error |
installed contract explains the failure and the local correction passes |
intentional-api-change |
official migration or source history proves a deliberate change |
upstream-active |
current checked code reproduces and an upstream record matches |
fixed-unreleased |
the matching fix is merged but no verified published package contains it |
fixed-released |
a published package contains the fix and the same reproduction passes |
not-reproduced |
the candidate configuration does not reproduce the local failure |
unrelated |
API, backend, symptom, affected range, or reproduction differs materially |
insufficient-evidence |
reproduction, containment, fix, or release proof is missing |
Closed is not a classification, and merged is not evidence that an npm release contains the fix.
This step is complete when every inspected candidate has exactly one supported classification.
6. Hold a constant version matrix when version-dependent
When the diagnosis depends on version behavior, change one Three.js version at a time while holding the reproduction, backend, browser/GPU, imports, assets, and assertion constant. As evidence permits, record the installed version, last known good, first bad, fixing commit, first published fixed release, and current checked release.
This step is complete when every conclusion about affected range or release availability follows from comparable rows rather than version labels.
7. Contain, verify, then choose one action
First identify the narrowest containment that protects the violated invariant. Then verify the proposed correction on the original reproduction. Recommend an upgrade only after proving the fixing commit, the first published package that contains it, and a passing reproduction on that package.
Choose one action:
- application fix for misuse or invalid state;
- released upgrade for a verified published fix;
- bounded workaround or pin with scope and removal condition;
- upstream report when current checked code reproduces without a matching case;
- blocker when required evidence is unavailable.
This step is complete when the chosen action has a passing or falsifiable verification, names its version/backend scope and side effects, and does not claim more than the evidence supports.
Report and stop
Return the root cause, installed result, relevant upstream issue/PR and fixing commit, affected range, first published fixed release, classification, fixed version result, regression assertion, one decision, and limitations.
Stop when one conclusion has direct local evidence and, when upstream is involved, direct primary-source/release proof. Also stop when all plausible candidates are classified and the exact missing evidence is explicit. Do not collect unrelated issue IDs after the action is settled.