Recipe catalog / root-cause-depth

Grade the depth of a root cause analysis

How deep does analysis go in explaining a failure, on a five-level rubric from restating the symptom to naming a verified systemic cause?

You review corrective action requests, nonconformance dispositions, or incident write-ups and want to flag analyses that stop at the symptom or the immediate cause before a quality reviewer accepts them.

Explore this recipe interactively · Source and implementation guide

Use root-cause-depth in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { rootCauseDepth } from 'jev-recipes/root-cause-depth';

const result = await rootCauseDepth({
  "analysis": "Line 3 stopped twice this week because the conveyor drive motor tripped on overtemperature. The motor overheated because the cooling fan intake was packed with cardboard dust. The intake was clogged because the weekly intake cleaning task was not performed for about eleven weeks. That task was dropped when the preventive maintenance schedule was migrated to the new CMMS in June: the migration checklist had no step to reconcile task counts between the old and new systems, and no one was assigned to own the migration, so the missing task was never noticed.",
  "minConfidence": 0.8
});
console.log(result);

Input contract

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "analysis": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "analysis"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "score": {
        "type": "number",
        "minimum": 0
      },
      "level": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "depth": {
        "type": "string",
        "enum": [
          "symptom",
          "immediate",
          "contributing",
          "systemic",
          "verified"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "score",
      "level",
      "confidence",
      "probabilities",
      "depth"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo root-cause-depth.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "score": 2.88,
  "level": 3,
  "confidence": 0.82,
  "probabilities": {
    "0": 0.01,
    "1": 0.02,
    "2": 0.1,
    "3": 0.82,
    "4": 0.05
  },
  "depth": "systemic"
}

Evaluation evidence

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

• Grades how far the stated chain of causes reaches, not whether any link in it is true. A deep analysis can be deeply wrong.
• Rewards what analysis states, so a correct cause left implicit grades shallow.
• Does not know your CAPA procedure or which depth is required for a given defect class. Acceptance thresholds belong in application code.

Related recipes

• causal-attribution: Use causal-attribution to label whether an explanation blames the person or the situation, rather than how deep the causal chain goes.
• explanation-level: Use explanation-level to grade how much reasoning an answer shows for a conclusion, rather than how far a failure analysis traces its causes.