Roblox Diagnosis

Finding the cause of a reported symptom. Nothing here writes the fix and nothing here scores a codebase: this skill decides what is actually wrong and hands that answer on.

It exists because a bug report names a symptom, never a file. Reaching for the first plausible file and editing it produces a change that looks like a fix, passes review, and leaves the defect in place.

Goal, in priority order: cause → evidence → cheapest probe → clean handoff. A confirmed cause with narrow evidence beats a broad theory. Guessing costs more than asking.

This skill ships as part of a set and does not stand alone. Every reference it cites lives in ../best-practices/references/, the pool shared by all five roblox-optimum skills. Installing this directory on its own leaves those links pointing at nothing. If a reference will not open, the install is incomplete: say so rather than diagnosing from memory.

Session Invariants (must survive compaction)

ROBLOX DIAGNOSIS - INVARIANT CARD
1  A symptom is not a cause. Nothing is fixed until the failing path is
   named and shown to fail.
2  Ask first: which side owns this state, and does it replicate? Most
   Roblox defects are a client and a server disagreeing about a value.
3  An impossible state means an untrusted input. Ask whether a client
   could have produced it before concluding the code is wrong.
4  Studio is not the game. Play Solo, the Edit VM, absent latency, one
   client, and a higher frame rate each hide or invent failures.
5  Reproduce before editing. When it cannot be reproduced, say so and
   name the evidence that would settle it.
6  Change one thing per probe. Two changes at once forfeit the result.
7  Intermittent means a race, a yield, or a retry. Reach for those three
   before rereading logic that is correct in isolation.
8  Leave no residue. Prints, tags, instances, and test scripts added to
   observe are removed when the answer is found.
9  Never describe what a file contains without opening it. A hypothesis
   about unread code reads exactly like a finding and is not one.
10 Report the cause with the evidence that establishes it. Handing off a
   guess wastes the fix and the review after it.
11 User authority outranks this skill.

Everything below expands these; nothing below overrides them.

Which symptom is this

Resolved from the report before anything is read. The row decides where the cause is likely to live, not what the fix will be.

The full loop, the environment traps that fake a defect, and the stop conditions are in diagnosis.md. Read it when the row above does not settle the shape of the problem, or when the first hypothesis fails.

The loop

1. Restate the symptom as an observation. What was seen, by whom, where, and how often. "Data resets" is a conclusion; "the coin count showed zero after rejoining" is an observation. Ask for the missing half rather than filling it in.
2. Establish the environment. Authority mode, StreamingEnabled, community libraries, Studio-native or synced, and whether the report comes from Studio or a live server. Each changes what counts as impossible. Unresolved means unresolved.
3. Ask what changed. A defect that appeared has a cause that arrived: a recent edit, a new library, an engine release, a spike in players. When nothing changed, the defect is old and the trigger is new.
4. Form one hypothesis and name what would disprove it. A hypothesis nothing could refute is not a hypothesis. Prefer the one whose test is cheapest.
5. Narrow, then reproduce. Cheapest probe first, one change at a time. Reproduction is the line between a theory and a cause.
6. Confirm and hand off. State the failing path, the evidence, and the conditions under which it fails. Stop there.

Cheapest probe first

Each step costs more than the one above it. Do not skip upward without a reason.

1. Read what the report already contains: console output, error text, a screenshot, a time.
2. Read the owning code path, both sides of any pair: the fire and the receive, the create and the destroy.
3. A single-client playtest, watching the one value in question.
4. Two clients, whenever a remote, replication, or StreamingEnabled is anywhere near it.
5. A server-side probe emitting structured output on the suspect path.
6. Live telemetry, when the symptom only appears at a scale a playtest cannot reach.

Steps 3 through 6 run through the studio-ops skill, which owns how a session is driven and what a tool call will do before it runs.

When it is not a defect

Three answers end a diagnosis without a fix, and each is a real result:

• An exploit. The client sent something the server accepted. The code is not wrong in isolation; it is missing a validation that server-authority.md requires. This is the most common cause of a state the game "cannot" reach.
• Correct behaviour under a condition nobody stated. The rule fired as written, for a case the report did not mention. Say which condition, and let the user decide whether the rule is what they wanted.
• An environment artefact. Play Solo, the Edit VM, a discarded play-mode change, or a Studio-only frame rate. The place is fine and the observation was not of the game.

Before reporting a defect at all, the shapes that only look wrong are catalogued in false-positives.md.

Reporting

State the cause, then the evidence, then the conditions. One paragraph is usually enough.

Say plainly when the cause is unconfirmed, and name the one probe that would settle it. An unconfirmed cause reported as confirmed is worse than no answer, because the fix that follows is aimed at the wrong line and the defect survives it with a test around it.

Do not include the fix. Naming the failing path is the deliverable.

Handing off

• Writing the fix → the best-practices skill, which owns the layout, the comment rules, and the standards the fix has to land inside.
• Judging code that already exists, or scoring a project → the code-review skill.
• Driving a playtest, a sync toolchain, or an MCP connection → the studio-ops skill.
• Reading live evidence (data store entries through execute_luau, analytics through open_cloud_invoke) → open-cloud.md; report user ids and aggregates, never raw player values.

Before the fixed work is called done, the finishing gate is review-checklist.md.

User Authority

Guidance, not a mandate. Never edit code, remove a probe the user placed, or change a place's configuration on this skill's initiative. Investigate, report, and let the user decide what is fixed.