Skip to main content

​
Overview

Deep Investigation is Siclaw’s diagnostic engine for complex issues. It combines interactive investigation (you and the agent collaborate on triage and hypothesis formation) with automated validation (parallel sub-agents test hypotheses independently). Deep Investigation is activated only by explicit user action — it does not run automatically.

​
Workflow

​
Interactive Planning Loop

When you activate Deep Investigation, the agent enters an interactive triage cycle:
  1. Triage: The agent runs targeted commands to understand the environment and confirm the problem.
  2. Propose Hypotheses: The agent presents 3-5 ranked hypotheses for your review.
  3. Your Decision:
    • Confirm → proceeds to parallel validation
    • Adjust → provide feedback, agent re-investigates and proposes again
    • Skip → agent presents a conclusion based on current findings
This loop can repeat as many times as needed. Each round improves hypothesis quality with your domain knowledge.

​
Parallel Validation

After you confirm hypotheses, the deep_search engine validates them:
  • Up to 3 sub-agents run simultaneously, each validating one hypothesis
  • Sub-agents don’t share information — this prevents confirmation bias
  • Each agent produces a verdict: validated, invalidated, or inconclusive
If Investigation Memory has data, past investigations with similar patterns are injected to improve validation.

​
Conclusion

All evidence is synthesized into a structured report containing:
  • Root cause with confidence score
  • Causal chain (ordered steps from trigger to symptom)
  • Evidence references (which commands produced which findings)
  • Remediation steps (actionable next steps)
  • Structured extraction (category, affected entities, environment tags) → stored in Investigation Memory

​
Triggering Deep Investigation

​
Web UI

Click the magnifying glass toggle next to the message input.

​
Terminal (TUI)

> /dp "Intermittent 5xx errors on API gateway every 30 minutes"
Or press Ctrl+I to toggle DP mode, then type your question.

​
External API

Automations can drive an agent from outside Siclaw using the /api/v1/run endpoint with an API-key-scoped agent. Issue an API key in the Portal UI (agent detail page → API keys), then: 
curl -X POST https://siclaw.example.com/api/v1/run \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Intermittent 5xx errors on API gateway every 30 minutes"}'
The agent resolved from the API key runs synchronously and returns the assistant reply.

​
Traces

Every investigation produces a trace file (relative to where Siclaw was launched): 
.siclaw/traces/deep-search-2026-03-06T14-30-00.md
Traces include the investigation summary, evidence, and recommended next steps.