# Debug Oracle
Causal debugging that explains **why** things broke, not just what broke.
## What It Does
Instead of dumping 400 log lines and telling you "there are errors," it:
1. **Collects evidence** from Docker logs, systemd journal, git history, and system metrics
2. **Analyzes causal chains** — what event caused what, in temporal order
3. **Produces explanations** in natural language: "X failed because Y happened at time Z, caused by condition W"
## Installation
```bash
cd debug-oracle
uv venv
source .venv/bin/activate
uv sync
```
## Usage
```bash
# Quick system status
python -m oracle status
# Quick triage
python -m oracle triage "AgentForms is slow"
# Full investigation
python -m oracle investigate "Service X is returning 500s"
# Investigate specific containers
python -m oracle investigate "Database errors" -c agentforms-relay seedvault
# Check git changes too
python -m oracle investigate "Recent deploy broke something" -r /path/to/repo
# Different output formats
python -m oracle investigate "Error" --format text
python -m oracle investigate "Error" --format json
# LLM endpoint (defaults to local Qwen on :8080)
python -m oracle investigate "Error" --llm-url http://127.0.0.1:8080/v1
```
## Architecture
```
oracle/
├── config.py # Configuration
├── models.py # Data models
├── main.py # CLI entry point
├── ingest/ # Data collection
│ ├── docker.py # Docker logs + health
│ ├── systemd.py # Systemd journal
│ ├── git.py # Git history
│ └── system.py # System metrics (psutil)
├── reason/ # Causal analysis
│ ├── engine.py # LLM reasoning engine
│ └── prompts.py # Causal reasoning prompts
└── output/ # Output formatting
└── formatter.py # Rich/text/JSON output
```
## Design Philosophy
**Bad:** "Error X occurred at line Y."
**Good:** "X failed because Y happened at time Z, caused by condition W."
The oracle doesn't list errors. It produces causal explanations connecting symptoms → events → root cause → recommendation.
## v1 Limitations
- Single LLM call (no iterative reasoning)
- No persistent knowledge base
- No automated fix suggestions
- Causal chain extraction from LLM output is best-effort
## Roadmap
- [ ] Temporal correlation engine
- [ ] Knowledge base of known failure patterns
- [ ] Automated remediation suggestions
- [ ] Watchdog mode (continuous monitoring)
- [ ] Integration with incident management