hypothesis

hypothesis — Phase 4 Orchestration

Version: 3.0.0 Phase: 4 — Hypothesis + Causation Analysis MCP Tools: None — CAPPY reasons directly from inv_context.json and evidence files Gate: coherence ≥ 85% (see skills/gate/SKILL.md) Reasoning Libraries: skills/sherlock/SKILL.md, skills/recon/SKILL.md, skills/synthesis/SKILL.md, skills/gate/SKILL.md

---

Status Output (MANDATORY — print before any tool call)

At the very start of execution, output this exact block:

[ Phase 4 — Hypothesis ]
Tools: direct reasoning — no external tools

Then before each tool call, output a one-liner: → {tool-name} {key parameter}

---

Purpose

Execute Phase 4 hypothesis generation and falsification entirely through direct reasoning. There is no meta-orchestrator for this phase — cappy_synthesis has been retired because it was Claude prompting Claude through a Rust wrapper with no added value. CAPPY reads the evidence directly, applies Tree of Thoughts, falsifies each branch adversarially, and surfaces only survivors.

This is the most reasoning-intensive phase. Apply the full chain: OBSERVE → CORRELATE → HYPOTHESIZE → FALSIFY → SURVIVE.

---

Procedure

Step 1 — Load investigation state

Read {case_dir}/inv_context.json. Extract:

• Phase 2: top patterns, confidence score, SF context
• Phase 3: key errors, timeline events, pattern correlations, evidence gaps

Also re-read the 2-3 most significant evidence files directly (use Read tool) to anchor reasoning in raw data, not just tool summaries.

Step 2 — OBSERVE

From inv_context.json Phase 2-3 data, list every verified claim. Do not add interpretation yet — just what the evidence shows.

Step 3 — HYPOTHESIZE — generate candidate root causes

Based on STRONG/PARTIAL patterns + Phase 3 findings, generate 2-4 candidate hypotheses. Each hypothesis must:

• Name a specific mechanism (not "config issue" — "X setting missing causes Y behavior")
• Be falsifiable (there must be evidence that could disprove it)

Step 4 — Build Tree of Thoughts (per skills/sherlock/SKILL.md)

<tree>
ROOT: "{symptom}"

  BRANCH-A: {hypothesis_1} [confidence: certain | high | medium | low]
    EVIDENCE-FOR: {citation} → {file:line}
    EVIDENCE-AGAINST: {citation} → {file:line or "none found"}
    ENVIRONMENT-FIT: Applies to {product} {version} {deployment_type}? Y/N

  BRANCH-B: {hypothesis_2} [confidence: ...]
    EVIDENCE-FOR: ...
    EVIDENCE-AGAINST: ...
    ENVIRONMENT-FIT: ...
</tree>

Step 5 — FALSIFY each branch adversarially

For each branch, identify the ONE piece of evidence that would disprove it, then actively search for it:

• Use Read tool on relevant evidence files
• Decode embedded artifacts (base64, X.509 certs, JWTs) — surface-level field checks are insufficient
• Check version compatibility, timestamp ordering, configuration values

<falsify>
  BRANCH-A: "{hypothesis_1}"
    DISPROOF TARGET: {what would prove this wrong}
    SEARCHED: {files/fields/artifacts examined}
    RESULT: DISPROVED — found at {file:line}
            | NOT DISPROVED — searched {X, Y, Z}, no contradicting evidence
</falsify>

Step 6 — Asymmetry check

If the proposed cause exists across multiple systems but the effect is asymmetric (one system affected, others not), the cause alone is insufficient. Search for differentiating factors before declaring a root cause.

Step 7 — SURVIVE

<survive>
  BRANCH-A: SURVIVES | ELIMINATED | INCONCLUSIVE — {reason with citations}
  BRANCH-B: ...

  PRIMARY HYPOTHESIS: {the strongest survivor}
  EVIDENCE CHAIN: {ordered file:line citations supporting it}
  WEAK ASSUMPTIONS: {claims that lack direct evidence — to be resolved in Phase 5}
</survive>

If ALL branches are eliminated: do NOT fabricate a hypothesis. Flag "insufficient evidence" and trigger SP-6 escalation.

Step 8 — Validate environment fit (per skills/recon/SKILL.md)

Search cortex-docs and jira_search to confirm the hypothesis applies to this customer's exact environment:

~/.cappy/tools/web-fallback/websearch.sh "site:docs-cortex.paloaltonetworks.com {hypothesis keywords} {product} {version}" 5

Does the documented behavior match what was observed? Note version-specific caveats.

Similar resolved cases — has this hypothesis been confirmed in a prior case?

// **SF CLI (closed TAC cases — primary)**:
```bash
SANDBOX_OK=$(docker ps --filter name=cappy-client --format "{{.Status}}" 2>/dev/null | grep -c "Up")
if [ "$SANDBOX_OK" -gt 0 ]; then
  docker exec cappy-client sf data query \\
    --query "SELECT CaseNumber, Subject, Product__c, Status, Cause__c, Resolution_Steps__c FROM Case WHERE (Subject LIKE '%{hypothesis_root_cause_keywords}%' OR Description LIKE '%{hypothesis_root_cause_keywords}%') AND Status = 'Closed' LIMIT 5" \\
    --target-org panw --json 2>/dev/null
fi

Fallback (sandbox unavailable or auth expired):

mcp__mcp-gateway__mcp_jira__jira_search({
  jql: "project IN (XSUP, XSOAR) AND text ~ \"{hypothesis_root_cause_keywords}\" AND status = Closed ORDER BY updated DESC",
  fields: "summary,status,resolution",
  limit: 5
})

TAC playbooks and KCS articles — does a playbook exist for this hypothesis?

mcp__mcp-gateway__confluence__confluence_search({
  query: "{hypothesis keywords} {product}",
  limit: 10
})

A resolved case or KCS article confirming this root cause raises hypothesis coherence directly. Cite as SECONDARY evidence.

Step 9 — Check Phase 4 gate (per skills/gate/SKILL.md)

alignment_score = (evidence-supported claims) / (total hypothesis claims) × 100

IF alignment ≥ 85% AND ≥ 1 hypothesis survived falsification: gate PASSES.

IF alignment < 85%: identify which claims lack evidence. Do not lower the bar — flag for Phase 5 to resolve.

IF all hypotheses eliminated: gate FAILS. Escalate via SP-6. Do not fabricate.

Step 10 — Classify the issue

Based on the surviving hypothesis and evidence, classify the issue. This classification drives the loop decision and determines the output type.

Classification	Criteria
customer_config	Root cause is a misconfiguration or deployment issue — customer can resolve it. Evidence shows incorrect setting, missing config, or wrong deployment topology.
product_bug	Root cause is a code defect, regression, or missing feature. Evidence shows behavior deviating from documented expected behavior in the customer's version.
known_issue	Hypothesis matches an existing pattern with a documented resolution. Pattern confidence is DEFINITIVE or STRONG.
novel_issue	No pattern match, no JIRA precedent, never documented. Engineering investigation required.
unclear	Insufficient evidence to classify definitively. Requires another loop pass.

Also extract refined symptom keywords for potential loop re-triage. These are specific error codes, API names, or component terms extracted from Phase 3 evidence that were not in the original symptom description.

Step 11 — Prepare Phase 5 targets (per skills/synthesis/SKILL.md)

Use skills/synthesis/SKILL.md to extract key assumptions and generate specific Phase 5 validation targets. These feed directly into skills/resolution/SKILL.md Step 1.

---

Return Format

{
  "phase": 4,
  "gate_status": "PASS | FAIL",
  "coherence_score": 0,
  "threshold": 85,
  "hypothesis": "{primary hypothesis — specific mechanism, not generic label}",
  "confidence_tier": "DEFINITIVE | STRONG | MODERATE | WEAK",
  "branches_explored": 0,
  "branches_survived": 0,
  "branches_eliminated": 0,
  "supporting_evidence": [{ "claim": "...", "citation": "file:line" }],
  "contradictions": [{ "claim": "...", "citation": "file:line" }],
  "weak_assumptions": [],
  "environment_fit": { "product": true, "version": true, "deployment": true },
  "phase_5_targets": ["..."],
  "issue_classification": "customer_config | product_bug | known_issue | novel_issue | unclear",
  "issue_classification_confidence": "high | medium | low",
  "refined_symptom_keywords": ["..."],
  "recommendation": "Proceed to Phase 5 | Gate blocked: {reason}",
  "recovery_options": []
}

Do NOT proceed to Phase 5. Return this JSON to Main Claude.