nobrainer-rca git:20261102.814dd35A

Immutable. This exact content never changes and is served at /api/v1/blob/a03f32888d8b03ba.

---
name: nobrainer-rca
description: "Use when an incident, regression, test failure, outage, wrong value or unexpected system behavior has an unclear cause and needs an evidence-bound diagnosis before anyone proposes a fix. Aliases: nb-rca, deep-rca."
---

# NoBrainer Root Cause Analysis

Explain a specific observed failure with a continuous evidence chain. Diagnose
before proposing or implementing a fix. Use the project's maintained debugging
and tracing capabilities for reproduction and hypothesis tests; this skill owns
incident framing, adaptive independent investigation, evidence reconciliation
and a durable RCA verdict.

Do not use for broad code auditing, risk review, or choosing among already-known
solutions. Those are different tasks.

## Investigation contract

Freeze the incident before searching:

```text
SYMPTOM: <literal observation>
EXPECTED: <contract or baseline>
WHEN: <timestamp/window/version>
ENVIRONMENT: <runtime, release, region/account boundary>
REPRODUCTION: REPRODUCIBLE | INTERMITTENT | NOT_REPRODUCED
IMPACT: <users/data/money/availability>
LAST_KNOWN_GOOD: <version/time or UNKNOWN>
FROZEN_INPUTS: <logs, commit, config snapshot, request IDs or UNKNOWN>
WRITE_AUTHORITY: READ_ONLY unless explicitly expanded
```

Ask one focused clarification only when a missing value changes where or how to
investigate. Otherwise mark it `UNKNOWN` and gather evidence. Never put secrets
or full sensitive payloads in prompts or reports.

## Calibrate investigation breadth

MAIN reconciles incident evidence. Delegate independent bounded questions promptly
to native investigators under nobrainer-tech-flow
[team execution](../nobrainer-tech-flow/references/delivery.md#coordinated-team-execution).
Select relevant questions using the requested breadth:

- `LIGHT`: one deterministic local failure and short trace; a tightly coupled probe may stay in MAIN.
- `STANDARD`: multiple layers, timing, state, configuration or external dependencies.
- `HIGH`: production incidents, data/money, intermittent concurrency, security boundaries or conflicting evidence.

Possible perspectives are forward trace, backward data lineage, timeline/logs,
configuration/state, dependency boundary, cache/concurrency/timing, hypothesis
killer, and similar-incident history. Assign only relevant ones. Ten generic
agents are not rigor; coverage of real uncertainty is rigor.

Each investigator gets the same frozen incident identity but a disjoint question
and returns `FINDING`, literal `EVIDENCE`, source/time, confidence, alternatives
disproved, and blind spots. A timeout, malformed response, stale log, partial
trace, or inaccessible runtime is missing evidence, not agreement.

## Evidence pipeline

### 1. Establish the baseline

Read repository instructions, actual checkout, dirty state, release/commit,
current config schema, tests, logs and incident artifacts. Distinguish the code
now on disk from what ran during the incident. Do not treat documentation or
memory as runtime state.

Reproduce the symptom with the smallest safe input when possible. A production
write, credential use, external message, destructive query or instrumentation
that changes behavior requires its normal owner gate.

### 2. Build a causal graph

Trace from trigger to symptom and backward from bad output to source. At every
component boundary record:

- input value and timestamp;
- transformation/decision and exact code/config version;
- output value and destination;
- evidence reference and remaining gap.

Build a timeline when chronology, cache, retry, race, scheduling or deployment
can matter. Do not invent timestamps or fill gaps with narrative.

### 3. Test hypotheses

State one falsifiable hypothesis at a time: "X caused Y because Z." List the
evidence that would confirm and disprove it, then run the smallest safe test that
changes one variable. A failed hypothesis becomes recorded evidence; do not pile
additional guesses onto it.

When fix-like experiments exhaust the
[Flow corrective-attempt budget](../nobrainer-tech-flow/SKILL.md), stop and question
the architecture with the owner. RCA itself does not implement a fix.

### 4. Reconcile perspectives

Deduplicate findings by causal link, not wording. Prefer evidence from the exact
incident/version over newer generic behavior. For conflicts, compare source,
time window, checkout and command. Run one bounded tie-breaker that seeks a
single discriminating observation.

Do not force one root cause when the evidence chain has a real gap. Use:

- `CONFIRMED`: continuous chain and alternatives materially disproved;
- `PROBABLE`: strongest supported cause with explicit missing evidence;
- `INCONCLUSIVE`: no cause crosses the proof threshold.

Contributing factors explain why impact was possible or worse; they are not
automatically the initiating root cause.

## RCA report

```text
RCA RESULT: CONFIRMED | PROBABLE | INCONCLUSIVE
RIGOR: LIGHT | STANDARD | HIGH

SYMPTOM / EXPECTED / IMPACT
  <frozen incident statement>

ROOT CAUSE
  <one cause, or NOT PROVEN>

EVIDENCE CHAIN
  1. <trigger/source + literal evidence reference>
  2. <transformation/boundary + evidence>
  3. <observable symptom + evidence>

TIMELINE
  <ordered events or NOT_APPLICABLE>

DISPROVED HYPOTHESES
  - <hypothesis + discriminating evidence>

CONTRIBUTING FACTORS
  - <factor + evidence>

DETECTION GAP
  <why existing test/monitor/guard did not catch it>

RECOMMENDED FIX CONTRACT
  <behavior to change, regression test and verification; no implementation>

CONFIDENCE / BLIND SPOTS
  <level, missing evidence, stale/inaccessible sources, failed investigators>

RECOVERY
  <incident containment already observed, rollback candidate, owner gate>

NEXT_ACTION
  <one exact diagnostic, approval, or separate fix task>
```

Every causal claim must be tagged as observed evidence or an inference from
named evidence. Never write "checked" without the command/readback or source
reference. Preserve sensitive details outside the public report.

## Stop boundary

End after diagnosis and fix contract. Do not silently change code, configuration,
data, production, credentials, monitoring, or retry policy. If the owner asks to
fix after accepting the RCA, start a separate bounded implementation with a
failing regression test through `nobrainer-build`, then return for fresh
verification and review.

## Persist the post-mortem

Diagnosis stays read-only. After the report, persistence is a separate write under
the project's `LEARNING_WRITE_POLICY` from Flow
[correction hooks](../nobrainer-tech-flow/references/correction-hooks.md):
save the report to `docs/incidents/<date>-<slug>.md` or the project's existing
incident home, write its one-line prevention to `tasks/lessons.md`, and turn the
`DETECTION GAP` into a regression test or a frozen scenario through the fix task.
Under `ASK` prepare those diffs; under `OFF` keep them in the report.