Root Cause Hypothesis Generation Prompt

This prompt is for senior QA engineers and developers who need to move from a defect report to a set of testable root cause hypotheses. It takes structured defect symptoms, system architecture knowledge, and recent change context as inputs, then produces ranked hypotheses with supporting evidence, contradicting evidence, and concrete next investigative steps. Use this prompt when you have a reproducible or well-documented defect and need to narrow the search space before diving into logs or debuggers. It is not a replacement for debugging tools or postmortem processes; it is a reasoning accelerator that makes investigative thinking explicit and reviewable.

The ideal user brings three things to this prompt: a detailed defect record (symptoms, reproduction steps, environment, observed vs. expected behavior), architectural knowledge of the affected system (component boundaries, data flow, dependency graph), and awareness of recent changes (deployments, config updates, dependency bumps, traffic shifts). The prompt works best when the defect is reproducible or at least well-characterized—intermittent failures with no pattern will produce weak hypotheses with low confidence scores. Before using this prompt, confirm you have enough symptom data to constrain the hypothesis space. If all you have is 'the app crashed once for a user,' start with a defect reproduction prompt instead.

Do not use this prompt as a substitute for systematic debugging, log analysis, or postmortem processes. It does not access production systems, query observability data, or run diagnostic commands. The hypotheses it generates are reasoning artifacts—they need empirical validation before they become conclusions. In regulated environments (healthcare, finance, safety-critical systems), treat the output as investigation guidance, not as a root cause determination. Always review hypotheses against actual evidence before acting on them, and maintain a clear audit trail of which hypotheses were tested and what evidence confirmed or ruled them out.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a senior QA architect, consuming structured defect information and producing a ranked list of root cause hypotheses. Each hypothesis must be supported by the provided evidence, acknowledge any contradicting evidence, and propose the next investigative step. The placeholders, marked with square brackets, must be replaced with real data from your defect tracking system, logs, and architectural documentation before execution.

codeCopy
SYSTEM: You are a senior QA architect specializing in root cause analysis for distributed systems. Your task is to generate evidence-backed root cause hypotheses from defect symptoms, system logs, and architectural context. You must reason step-by-step, ground every hypothesis in the provided evidence, and explicitly state your assumptions. Do not fabricate evidence or system behavior not present in the input.

USER:
**Defect ID:** [DEFECT_ID]
**Title:** [DEFECT_TITLE]
**Observed Behavior:** [OBSERVED_BEHAVIOR]
**Expected Behavior:** [EXPECTED_BEHAVIOR]
**Environment:** [ENVIRONMENT_DETAILS]
**Logs & Stack Traces:**

[LOGS_AND_STACK_TRACES]

codeCopy
**System Context:** [SYSTEM_ARCHITECTURE_CONTEXT]
**Recent Changes:** [RECENT_CODE_OR_CONFIG_CHANGES]
**Reproduction Rate:** [REPRODUCTION_RATE]

**Instructions:**
1.  Analyze the defect symptoms, logs, and system context.
2.  Generate a ranked list of 3-5 root cause hypotheses, ordered from most to least likely.
3.  For each hypothesis, provide:
    - **Hypothesis:** A clear, concise statement of the potential root cause.
    - **Supporting Evidence:** Specific evidence from the input (e.g., log lines, stack trace frames, recent changes) that supports this hypothesis.
    - **Contradicting Evidence:** Any evidence from the input that weakens or contradicts this hypothesis. If none, state "None found."
    - **Confidence Score:** A score from 1 (low) to 5 (high) indicating your confidence in this hypothesis based on the available evidence.
    - **Next Investigative Step:** A concrete, actionable step to validate or invalidate this hypothesis (e.g., a specific log query, a code inspection point, a test to run).
4.  Output the result as a JSON object matching the [OUTPUT_SCHEMA].

[OUTPUT_SCHEMA]:
{
  "defect_id": "string",
  "analysis_summary": "string",
  "hypotheses": [
    {
      "rank": "number",
      "hypothesis": "string",
      "supporting_evidence": ["string"],
      "contradicting_evidence": ["string"],
      "confidence_score": "number",
      "next_investigative_step": "string"
    }
  ]
}

[CONSTRAINTS]:
- Do not invent evidence. If the input lacks information, state your assumptions explicitly in the `analysis_summary`.
- The `next_investigative_step` must be a specific, executable action, not a vague suggestion.
- If the logs contain a clear exception, the top hypothesis must address it directly.

To adapt this template, replace the placeholders with data from your specific workflow. The [SYSTEM_ARCHITECTURE_CONTEXT] is critical for high-quality hypotheses; provide a brief description of the relevant services, data flow, and dependencies. For high-risk or regulated environments, ensure a human reviews the generated hypotheses before any action is taken based on them. The JSON output schema is designed for direct ingestion into an incident management or QA dashboard, enabling automated routing of the next investigative steps.

This prompt is designed to sit inside a defect analysis or incident review pipeline, not as a standalone chat interface. The application should collect structured defect symptoms, system knowledge (architecture docs, recent changes, known issues), and environment data before assembling the prompt. The model receives a complete evidence packet and returns ranked hypotheses, not a conversation. This means the harness must own input collection, prompt assembly, output validation, and the decision about what happens next with each hypothesis.

Input assembly: Before calling the model, gather the defect record (title, observed behavior, expected behavior, reproduction steps, stack traces, log excerpts), system context (affected service, recent deployments, dependency graph, known issues from a bug tracker or incident database), and any constraints (time window, environment scope). Map these into the [DEFECT_RECORD], [SYSTEM_CONTEXT], and [CONSTRAINTS] placeholders. If using retrieval-augmented generation, query your incident database and change logs for related failures and inject the top results into [SYSTEM_CONTEXT] with source timestamps. Model choice: Use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) because hypothesis generation requires causal reasoning across multiple evidence sources. Lighter models tend to produce shallow or generic hypotheses. Set temperature low (0.1–0.3) to reduce creative speculation while still allowing ranked alternatives.

Output validation: Parse the model response against the expected schema: each hypothesis must have a hypothesis_statement, supporting_evidence (array of specific observations), contradicting_evidence (array), confidence_score (0.0–1.0), and next_investigative_steps (array). Reject any hypothesis missing required fields or with empty evidence arrays. Validate that supporting_evidence items reference concrete symptoms, logs, or system facts from the input—not vague assertions. If confidence scores are all below 0.3 or all above 0.9 without justification, flag the output for human review. Retry logic: If validation fails (malformed JSON, missing fields, ungrounded evidence), retry once with the validation errors appended to the prompt as [PREVIOUS_OUTPUT_ERRORS]. If the second attempt also fails, escalate to a human analyst with the partial output and error details. Do not loop beyond two attempts.

Human review gate: Root cause hypotheses are high-stakes outputs—acting on a wrong hypothesis wastes investigation time and can delay real fixes. After validation passes, route hypotheses with confidence_score below 0.6 to a review queue where a senior engineer confirms or rejects the hypothesis before it drives action. For hypotheses above 0.6, the system can auto-create investigation tickets or link them to the defect record, but always preserve the full hypothesis payload (including contradicting evidence) so the next investigator sees the model's uncertainty, not just its top guess. Logging: Record the full prompt, model response, validation results, and review decision for auditability. This trace is essential for retrospective analysis when a hypothesis proves wrong and the team needs to understand why the model missed the real cause.