Symptom, mechanism, and root cause

1396. Lesson identity

Module

3.16 — Debugging

Lesson

Symptom, mechanism, and root cause

Academic type

Concept

Schema type

text

Order

1

Estimated content time

15–20 minutes

Estimated practice time

15–25 minutes

Total estimated time

30–45 minutes

This lesson establishes the vocabulary for reasoning from a visible failure toward a testable explanation. It follows 3.15 L2 — Build one outcome-focused check, where you created a check that produces useful evidence.

1397. Learning objective

After this lesson, you can separate observation from assumption in a bug report and label the symptom, hypotheses, mechanisms, and possible root cause that require testing.

1398. Why this matters

A report that says “the collision system is broken” mixes what happened with an explanation that may be wrong. That mixture sends debugging effort toward a guessed subsystem instead of toward evidence. Clear causal vocabulary helps you describe a failure precisely, direct an AI assistant without overclaiming, and choose the next diagnostic check. The goal is not to declare a root cause immediately; it is to preserve the path from evidence to explanation.

1399. Prior knowledge

You should be able to run or inspect an outcome-focused production check from 3.15 L2 — Build one outcome-focused check. You should also be familiar with arranging a check, acting, observing the result, and then diagnosing from the evidence. This lesson does not require you to edit the project.

1400. Core concept

A useful bug report distinguishes six related layers:

A symptom tells you how the failure manifests. An observation turns that symptom into bounded evidence by recording the conditions, action, and directly available result. For example, “the door remains closed” is a symptom; “after pressing Interact while standing beside the door, the door remained closed” is an observation.

These layers are related but not interchangeable. An observation is evidence. A hypothesis is a proposed explanation. A mechanism describes how that explanation would produce the result. A root cause is a deeper, actionable condition—not merely the most technical-sounding label.

A single symptom can have multiple possible mechanisms. “The character does not move” might result from missing input, a blocked movement rule, a frozen state, or a presentation problem that hides movement. Do not select among those explanations until a check distinguishes them.

1401. Mental model

Use the S-O-A-H-M-R chain:

Symptom → Observation → Assumption to challenge → Hypothesis → Mechanism → Possible root cause to verify

Ask a different question at each step:

1. Symptom: How is the failure visible to a user or system observer?
2. Observation: What exactly happened, under what conditions, and what evidence is directly available?
3. Assumption: What am I treating as true without evidence?
4. Hypothesis: What testable explanation could account for the observation, and what evidence would support or reject it?
5. Mechanism: By what sequence would that explanation create the result?
6. Possible root cause: What underlying condition might need correction, and is it currently supported, rejected, or still unverified?

The arrows do not mean that every investigation moves in a straight line. A check can reject a hypothesis and send you back to generate another one. The model protects the boundary between what you know and what you are proposing.

1402. Concrete example

Suppose a test produces this report:

“The pickup system is broken. The player walks over the key, but the door does not open because the pickup trigger is not firing.”

Separate it before debugging:

• Symptom: The door remains closed after the player encounters the key.
• Observation: In the arranged test, the player overlapped the visible key; after moving to the door, the door remained closed.
• Assumption: The pickup trigger did not fire.
• Hypotheses: The key was not registered as collected, or the door is checking a different inventory condition.
• Mechanism to test: The overlap may update the key's visual state without updating the inventory value that the door reads.
• Possible root cause: The pickup and door systems may use different identifiers for the same item.
• Current evidence status: Unverified; the observation does not expose the identifiers used by either system.
• Evidence needed: Record the identifier written during pickup and the identifier read by the door in the same arranged test.

The revised report does not claim that the identifier mismatch is proven. It records the manifestation, bounds the observation, exposes the assumption, and proposes a mechanism and possible root cause that a focused check can evaluate.

1403. Common mistake

The common mistake is treating the first plausible subsystem name as the root cause. Statements such as “the physics is broken,” “the event is unreliable,” or “the AI generated bad code” are broad assumptions, not diagnoses. They do not state what was observed, what condition was present, or what causal sequence connects the condition to the failure. Replace them with a bounded observation and a hypothesis that predicts evidence that could support or reject it.

1404. Guided practice

Rewrite the following report using the S-O-A-H-M-R chain:

“The health system is wrong. The player dies instantly because the damage event is firing twice.”

Use this procedure:

1. State the user-visible or system-visible symptom without naming a cause.
2. Write one observation containing the test setup, action, and visible or measured result. Do not include a causal explanation.
3. Identify the assumption hidden in the original report.
4. Write two competing, testable hypotheses. One may involve duplicate damage; the other must offer a different explanation. For each, predict evidence that could support or reject it.
5. Describe the mechanism for each hypothesis in one or two causal steps, then choose one discriminating check and state what result would support each mechanism.
6. Label one possible root cause. Mark its current evidence status as supported, rejected, or unverified, and state what evidence would be needed to verify it. Do not present it as proven unless the available evidence establishes it.

A strong observation might begin: “With the player at full health and one hazard contact arranged, the health display changed from full to empty during the contact.” It should not begin with “the damage event fired twice,” because that is already an explanation.

1405. Validation and evidence

Complete the attached practical assessment. Your submission must distinguish the symptom from the bounded observation and clearly label the observation, assumption, two hypotheses, mechanisms, possible root cause, evidence status, and discriminating check.

You have met the capability when another developer can determine:

• which statement describes the visible manifestation;
• which statement is directly supported by the stated test conditions;
• which claims remain unverified;
• how each proposed mechanism could produce the result;
• why the root cause is only possible at the current evidence level; and
• what check result would change the next debugging decision.

The task remains limited to classification and causal reasoning. The next lesson develops the fuller reproduction, narrowing, and validation write-up.

1406. Key takeaways

• A symptom is the visible manifestation of a failure; an observation records a specific symptom under stated conditions with directly available evidence.
• An assumption is an interpretation that still needs evidence.
• A useful hypothesis proposes a testable explanation and predicts evidence that could support or reject it.
• A mechanism describes the causal sequence from a condition to the observed result.
• A possible root cause must be labeled with its current evidence status and the evidence needed to verify it.
• Keep competing explanations visible until a discriminating check separates them.

1407. Next lesson

Continue to 3.16 L2 — Reproduce, narrow, validate / Reproducir, acotar, validar.

1408. Diagnose and recover (fix-git-regression)

Open academy-fixtures/labs/git-regression. Run node run.mjs. Map symptom → mechanism → recovery of known-good. Then apply the same thinking if Pulse Loop validate.mjs regresses.

1409. Knowledge check