Agent Skills: Root Cause Investigation

Root Cause Investigation

Use this skill as a formal, evidence-governed causal investigation protocol. Do not frame the work as "find the root cause" unless the evidence supports a singular cause; frame it as discovering what happened, what mechanisms likely produced the outcome, what remains uncertain, and what actions would change future system behavior.

Core Stance

• Evidence, mechanism, and uncertainty are required for every causal claim.
• User explanations are inputs, not facts.
• Method choice is provisional and revisable.
• Human error is a symptom label, not an endpoint.
• Corrective actions must map to supported causes and controls.
• Formalism should create compact rigor, not ornamental ceremony.

Load References

Load only what the investigation needs:

• For panel roles and domain overlays, read references/personas.md.
• For method selection and method-specific data requirements, read references/methods.md.
• For investigation files and output structures, read references/artifact-templates.md.
• For pressure-testing the skill across domains, read references/evaluation.md.

Formal Workflow

0. Agent-to-Panel Mode

When another coding agent invokes this skill from a separate tmux pane/session, treat that agent as the incident owner and implementation counterpart. Keep the panel independent enough to challenge its framing, but make outputs directly consumable by that first agent.

In this mode:

• run in the same working directory as the implementation agent unless the user explicitly asks for a central panel repo; confirm pwd if there is any doubt
• ask the implementation agent for the case frame, target repos/files, observed evidence, suspected fix, current validation state, and open questions
• write output under ./investigations/active/RCA-YYYY-NNN/ in that working repo, or return a handoff block if file output is not appropriate
• prefer compact implementation-control feedback over long narrative
• include owner surfaces and required artifact fields before recommending gates
• keep the model-mediated boundary explicit when models judge fulfillment

The handoff shape should be:

claim -> evidence class -> owner surface -> gate level -> command/gate -> required artifact fields -> pass/fail -> residual risk

1. Case Framing

Before choosing methods, gather a minimum viable case frame:

• Event definition: what happened, when, where, and what changed from expected operation.
• Consequence and decision need: harm, loss, near miss, customer impact, compliance exposure, disruption, or learning goal.
• System boundary: people, software, process, equipment, policy, vendors, environment, organization.
• Evidence inventory: logs, timelines, interviews, records, metrics, tickets, artifacts, observations.
• Known uncertainty: missing, disputed, inferred, sensitive, or politically constrained information.
• Recurrence question: explanation, prevention, accountability, redesign, learning, or documentation.
• Action authority: what the user can actually change.

If these are missing, interview the user before selecting methods. Ask for the highest-value missing inputs first.

2. Provisional Method Stack

Select a provisional stack, not "the method." Explain why each method fits the current case and what would make the stack change. Most formal investigations start with timeline or sequence reconstruction, then add methods such as barrier analysis, change analysis, fishbone, fault tree, systems mapping, or human factors review as evidence demands.

3. Evidence-Led Analysis

Run selected methods as instruments. Maintain a causal hypothesis register with:

• hypothesis statement
• evidence supporting it
• evidence against it
• mechanism connecting it to the event
• confidence and uncertainty
• tests or corroboration needed
• actionability

Do not let method outputs become conclusions without this register.

4. Evidence Gap Loop

When the panel lacks material input, pause or mark provisional status. Classify gaps:

• blocking: cannot proceed responsibly
• material: can proceed with reduced confidence
• optional: useful but not necessary

Ask for the top three decision-relevant missing items. After new evidence arrives, add it to the evidence ledger and amend the affected phase rather than silently patching the narrative.

5. Disconfirmation

Before synthesis, run a challenger pass:

• What alternative explanation fits the same facts?
• What evidence would prove the leading hypothesis wrong?
• What cause is plausible but unsupported?
• Where is sequence being mistaken for causation?
• Where are we overfitting to the user's first story?

6. Synthesis and Actions

Separate:

• event description
• proximal triggers
• contributing conditions
• failed or missing controls
• systemic causes
• contested or unresolved questions
• residual uncertainty

Corrective actions must state the mechanism by which they reduce recurrence or impact. Classify each action as prevention, detection, mitigation, recovery, or learning, and include owner/authority, verification signal, and failure mode.

For implementation-facing investigations, make every major hypothesis falsifiable:

• distinguish current proven defects from historical or already-fixed observations
• identify owner repositories and file/function-level owner surfaces where evidence supports them
• map contract fields across producer, consumer, and survival test
• define runnable gates with gate level (unit, scenario, live-browser, audit, or manual), command, expected artifact, and pass/fail condition
• name the artifact shape up front: exact fields to persist, where they should be stored, and which field proves the relevant claim
• require a scenario evidence tuple before accepting "it worked" as evidence
• preserve model-mediated boundaries: code binds mechanical evidence and schemas; models judge semantic fulfillment; code validates schema and evidence refs

When giving implementation feedback, prefer this compact control shape:

claim -> evidence class -> owner surface -> gate level -> command/gate -> required artifact fields -> pass/fail -> residual risk

For cross-domain investigations, preserve the same evidence/mechanism/action kernel while changing only the domain overlay: vocabulary, evidence sources, control model, method fit, and validation gates. Do not let domain personas become style transfer; they must improve evidence selection and control reasoning.

Panel Discipline

Use the lean core panel from references/personas.md: investigation lead, evidence steward, timeline/change analyst, systems/human factors analyst, corrective action reviewer, challenger, and a selected domain overlay. Add method-specific specialists only when their method is actually in use.

Avoid roles that incentivize premature convergence, such as "root cause finder," "blame assessor," or method zealots.

Artifact Policy

For substantial investigations, create or update an investigation folder:

investigations/active/RCA-YYYY-NNN/
  intake.md
  evidence-ledger.md
  method-stack.md
  timeline.md
  causal-hypotheses.md
  evidence-gaps.md
  disconfirmation.md
  field-contract-map.md
  scenario-evidence.md
  implementation-control-feedback.md
  agent-handoff.md
  causal-synthesis.md
  corrective-actions.md
  learning-review.md
  metadata.json
  method-analyses/
  artifacts/
  conversations/

Create the folder in the current working directory by default. In two-agent tmux mode, that should be the same repo/directory as the implementation agent so the handoff is findable by the first agent. Use only artifacts that serve the case. Essential artifacts are case framing, evidence ledger, causal hypothesis register, method rationale, selected method analyses, evidence gaps, disconfirmation, causal synthesis, corrective actions, and learning review. Full transcripts and diagrams are optional, not required.

If invoked by another agent, always provide a consumable handoff: either write agent-handoff.md in the investigation folder in the shared working directory or return a clearly delimited handoff block in the pane for the initiating agent to paste or relay.

Red Lines

Do not:

• promise a definitive root cause
• default to 5 Whys
• treat fishbone branches as causes
• treat absence of evidence as evidence of absence
• accept "training," "remind people," "be careful," or "human error" as sufficient action
• hide uncertainty to make the result feel complete
• invent domain facts through personas