abductive-triage

name	abductive-triage
description	Structured diagnostic reasoning for AI agents investigating incidents, failures, and unexpected behavior. Teaches agents to resolve coordinate mismatches first (majority of incidents), then build timelines, generate competing hypotheses, identify discriminating evidence, and produce portable investigation artifacts. Use when asked to create a triage workflow, investigate an incident, debug a failure, or encode a diagnostic process.
license	GPL-3.0
metadata	{"author":"TGPSKI","version":"2.0"}

Abductive Triage - Skill Instructions

Your job is to help the user investigate diagnostic problems using structured abductive reasoning, or to create reusable triage workflows for their repository.

References to examples and templates below are relative to the skill directory where this file lives.

Your Task

When investigating a problem directly:

1. Resolve coordinates first — verify the reporter's methodology matches where the system operates
2. Apply the reasoning loop to the symptom, evidence, or alert
3. Produce a diagnostic artifact documenting findings, evidence, and remediation

When creating a triage workflow:

1. Understand their diagnostic domain - what class of problems they want to encode
2. Analyze their workspace - log sources, monitoring tools, configuration patterns
3. Generate workflow files in the current workspace, following the conventions below

---

Critical Principle

The most common root cause in operations incidents is a coordinate mismatch (human checked the wrong path/endpoint/environment), not a system bug. The methodology is structured to surface this BEFORE any deep analysis begins.

The Reasoning Loop

Every investigation draws from the activities below. The loop is now structured in two tiers:

Tier 1 — Fast Path (resolves majority of incidents):

Intake → Adversarial Review → Resolve Reader → Resolve System Path → Compare → Ground Truth

Tier 2 — Deep Investigation (only if Tier 1 outputs COORDINATES VERIFIED):

Timeline → Hypothesize → Discriminate → Narrow → Contain → Artifact

Do not enter Tier 2 until Tier 1 confirms the reporter's observation is at the correct location. A coordinate mismatch at Tier 1 resolves the incident immediately — the system is working correctly, the observation was at the wrong location.

---

Evidence Hierarchy

Every claim in the investigation carries a source label:

Label	Source	Trust Level
DEFINITIVE	System output (CLI result, log line, API response, timestamp)	Trustworthy — safe to act on
CONFIG	Deployment configuration (settings, specs, infrastructure-as-code)	What SHOULD happen
SOCIAL	Multiple humans agreeing in a thread	Hypothesis only — not evidence
ANECDOTAL	Single human's recollection ("I believe...", "I think...")	Unreliable — needs verification

Human consensus is not evidence. If multiple people agree "system X doesn't do Y," that is SOCIAL confidence — a shared hypothesis, not a verified fact. When SOCIAL claims contradict CONFIG evidence, do not defer to social proof. Resolve with a ground truth check.

---

Tier 1: Intake & Coordinate Resolution

Intake

Capture the symptom exactly as reported. Extract ALL facts into a table:

Tag	Meaning
STATED	Directly quoted or explicitly declared
INFERRED	A conclusion the investigator draws
MISSING	Critical to resolution but not provided

| Fact | Source | Tag |
|------|--------|-----|
| {exact claim} | {who/where} | STATED/INFERRED/MISSING |

Adversarial Review

For each INFERRED fact: "What is the simplest alternative that makes this wrong?"

For each MISSING fact: "Could this single fact resolve the entire issue?" Score 1-5.

Any MISSING fact scoring 4-5 MUST be resolved before proceeding.

Resolve the Reader

What did the reporter actually check to confirm the symptom?

This must be evidenced in the report — not derived from what the system is configured to do. The reporter's methodology and the system's path are independent until proven same.

If the methodology is not shown in the report, ask:

"What exact command/path/tool did you use to verify? This may close the case immediately."

Resolve the System Path

Where does the system actually read/write? Derived from deployment configuration.

Compare (Gate)

REPORTER checked: {path from context/user}
SYSTEM uses:      {path from configuration}

• Different → COORDINATE MISMATCH — incident resolved, skip to remediation
• Same → COORDINATES VERIFIED — proceed to Tier 2
• Unknown → ask, do not proceed

Ground Truth Check

Before closing the gate, validate with a non-destructive live system read. Confirms the CONFIG-derived conclusion against actual system state.

---

Tier 2: Investigation

Only entered when Tier 1 outputs COORDINATES VERIFIED.

Timeline

Build a state/timestamp model before arguing cause:

| Time (UTC) | Event | Source |
|------------|-------|--------|

The timeline is the foundation. Without it, every hypothesis is speculation.

Hypothesize

Generate at least 2 competing explanations. Label evidence by confidence (Definitive, Heuristic, Correlated). Encode as tables, not prose.

Hypothesis	Prior	Supporting Evidence	Contradicting Evidence	Discriminating Check
{H1}	{H/M/L}
{H2}	{H/M/L}

Discriminate

Identify the single cheapest check that eliminates the most hypotheses. State the check, its expected outcomes, and its cost before executing.

Coordinate system verification: Before concluding a check returned unexpected results, verify you're in the correct coordinate system (environment, path, namespace, time window, identifier, account/region).

Narrow

Execute the check. Update the table. Collapse eliminated hypotheses:

• Single survivor with definitive evidence → root cause found
• Multiple survive → return to Discriminate
• None survive → generate new hypotheses (outside current mental model)

Contain

Take the minimum action to stop further damage while preserving evidence:

• Stop the bleeding before planning surgery
• Preserve evidence (capture before restarting)
• Set an expiry on temporary measures
• Document every action with a timestamp

Artifact

Produce a portable, inspectable investigation document:

1. Executive Summary (2-3 sentences)
2. Findings (each with: evidence table, exposure window, remediation)
3. Timeline (updated with investigation events)
4. Open Actions (prioritized: Critical / High / Medium)

Use the template in templates/single-incident.md or adapt to user conventions.

---

Evidence-Hypothesis Tables

Encode ALL conditional reasoning as tables, not prose:

Bad:

"It could be a sync failure, or maybe they're looking at the wrong path."

Good:

Hypothesis	Prior	Key Evidence	Discriminating Check
Wrong path	High	Migration active	Read both path prefixes
Sync failure	Medium	User reports mismatch	Check updated_at metadata

---

Output Structure

Single-Incident Triage

Use when the investigation completes in one session.

.agents/skills/{domain}-triage/
└── SKILL.md

Multi-Phase Investigation

Use when the investigation spans multiple sessions.

.agents/skills/{domain}-triage/
├── SKILL.md                                    # Router (entry point)
└── references/
    ├── phase-01-intake-coordinates.md         # Intake + coordinate resolution (fast path)
    ├── phase-02-investigate.md                # Hypothesis generation + discrimination
    └── phase-03-remediate-doc.md              # Containment + artifact production

Characteristic	Single-incident	Multi-phase
Completes in one session	Yes	No
Spans days/weeks	No	Yes
Produces 1 artifact	Yes	Yes (iteratively updated)
Multiple findings	Possible	Expected

---

Conventions

Frontmatter

Every triage workflow starts with YAML frontmatter:

---
name: triage-workflow-name
description: "What class of problems this workflow investigates"
metadata:
  author: team-name
  version: "1.0"
  parent: router-name              # Phase files only
compatibility: "Required tools"    # Router and single-file only
---

Tier 1 → Tier 2 Flow

Every investigation follows the two-tier approach:

Tier 1 — Intake, adversarial review, coordinate resolution. Resolves the majority of incidents without deep analysis. Configuration reads only. No source code reading.

Tier 2 — Timeline, hypothesize, discriminate, narrow. Only entered when Tier 1 confirms coordinates match. Deep analysis is now appropriate.

Router Rules (multi-phase)

The router:

• Captures the incident input (alert, thread, error message)
• Detects investigation progress by reading the artifact document
• Routes to the correct phase
• Never performs investigation itself

Progress detection uses the artifact as state:

Artifact State	Detected Phase
No artifact file	Phase 1: Intake + Coordinates
Has intake, no verdict	Continue Phase 1
Has COORDINATE MISMATCH verdict	Skip to Phase 3
Has COORDINATES VERIFIED + hypotheses	Continue Phase 2
Has findings, no remediation	Phase 3
All actions resolved	Investigation complete

Artifact Checkpoints

Every phase ends with an artifact checkpoint:

## Artifact Checkpoint

**File**: `sessions/{date}-{incident-slug}.md`

**Sections completed**:
- Intake table with fact extraction
- Coordinate comparison (verdict: {MISMATCH/VERIFIED})
- Ground truth validation

---

How to Create a Triage Workflow

Step 1: Understand the Domain

Ask the user:

1. What class of problems does this workflow investigate?
2. What evidence sources are available? (logs, APIs, config files, monitoring)
3. What are the common coordinate system errors? (the false alarms specific to this domain)
4. What tools do they use for investigation? (CLI tools, dashboards, MCP servers)

Step 2: Map the Coordinate Systems

Document the domain's coordinate system errors explicitly. These are the most common root causes and should be resolved FIRST:

| Coordinate | Values | Common Confusion |
|------------|--------|-----------------|
| Path/prefix | legacy-prefix/, current-prefix/ | Migration left both paths active |
| Environment | staging, production | Similar naming, wrong env checked |
| Identifier | resource_name, output_name, display_name | Different systems use different names |

Step 3: Identify the Common Hypotheses

For the domain, encode the 3-5 recurring root causes as the default table:

| Hypothesis | When to Suspect | Discriminating Check |
|------------|----------------|---------------------|
| Coordinate mismatch | Migration, multi-path, multi-env | Compare reporter path to system path |
| Config error | Recent git change | Diff current vs previous config |
| Credential rotation | Secret rotation in last 24h | Check metadata timestamps |
| Upstream dependency | Multiple services affected | Check upstream status |

Step 4: Generate the Workflow Files

Write files to .agents/skills/{domain}-triage/ in the user's workspace. Study the examples:

Example	Pattern	Good reference for
examples/supply-chain-ioc/	Multi-finding	Timeline across systems, exposure windows
examples/vault-path-confusion/	Coordinate system error	False alarm resolution, cheapest check
examples/hidden-pipeline-race/	Hidden mechanism	System behavior outside the mental model

Use templates/single-incident.md or templates/multi-phase-investigation/ as the starting skeleton.

Step 5: Enable IDE Discovery

Create symlinks from IDE-specific directories to the canonical location:

ln -s ../../.agents/skills/{domain}-triage .cursor/skills/{domain}-triage
ln -s ../../.agents/skills/{domain}-triage .claude/skills/{domain}-triage

---

Anti-Patterns

• Never skip coordinate verification. The first hypothesis is often "system is broken." The most common reality is "looked in the wrong place." Verify coordinates before investigating systems.
• Never jump to a fix before building a timeline. The fix addresses a hypothesis. Without a timeline, you don't know which hypothesis is correct.
• Never treat the first hypothesis as truth. Generate at least two.
• Never defer to social proof over system evidence. Thread consensus ("everyone agrees X is broken") is SOCIAL confidence. System output is DEFINITIVE. When they contradict, trust the system.
• Never substitute system path for reporter methodology. What the system is configured to do and what the reporter actually checked are independent until proven same. That gap IS the most common root cause.
• Never ask the user for information you can look up. Read the config, check the API, query the metadata. Then ask for what you couldn't find.
• Never use prose for conditional reasoning. Use evidence-hypothesis tables.
• Never discard contradicting evidence. Update the table. If the evidence is definitive, the hypothesis is wrong.

---

What NOT to Do

• Never read source code in Tier 1. Configuration files only. Source code analysis belongs in Tier 2.
• Never restart/modify systems before capturing diagnostic state. Logs, pod state, and API responses are evidence.
• Never present claims without confidence labels. Every claim is Definitive, Heuristic, or Correlated.
• Never skip the artifact. The Slack thread will scroll away. The session will end. The artifact persists.
• Never proceed past a gate with UNRESOLVED data. If the reporter's methodology is unknown, ask. Do not guess.