Engineering

How DEBUGER investigates failures — honestly, deterministically first, with AI as an optional refinement layer.

The investigation workflow

Every incident follows one pipeline. Each step produces artifacts you can inspect; nothing is claimed unless evidence supports it.

FAILURECOLLECT EVIDENCERECONSTRUCTROOT CAUSEEXPLAINRECOMMENDVERIFYDOCUMENT

Where evidence comes from

Manual entry	Paste errors, stack traces, or logs directly into a new incident.
Webhook capture	Point your services at a public endpoint; real requests are captured and inspectable.
Deployment & git context	Reference commits and deployments as evidence to ground temporal causality.
Integration API	Use an API key to push incidents and evidence programmatically.

Signal extraction & root cause

Evidence is parsed into signals — connection timeouts, SQL errors, CDN 502s, npm failures, TLS errors, rate limits, container restarts, secret scans, and more. Signals are grouped into root-cause categories; the earliest, most-supported category becomes the root-cause candidate. Co-occurring signals become contributing factors, and observable failures are tracked as symptoms.

Example conclusion

Root cause: Database connection pool exhausted under load (pool of 2 vs. request burst).
Contributing: deployment lowered pool_size; no retry/backoff on checkout path.
Symptom: Payments API returns 500 after 30s timeouts.

Confidence & honesty

Confidence is derived from signal support (multiple independent signals → higher confidence) plus corroboration from engineering memory.
Unknown signs explicitly. When nothing matches, DEBUGER says so and recommends structured heuristics rather than inventing a cause.
AI is additive, not authoritative. When configured, a model may refine the summary and reasoning narrative — but the root-cause conclusion, timeline, and recommendations are always computed first, and AI output is cached.
No fabricated facts. Presented incident stats are real counts from your data.

Fix verification

Verification runs deterministic checks only: scanning new evidence for the removed failure pattern, a security scan for exposed secrets, and — when you supply a target URL — an actual reproduction replay. A fix is marked verified only when a check ran and passed.

Engineering memory

When an incident is resolved it becomes a memory entry: root cause, resolution, confidence, and pattern. New incidents are compared against memory with term-frequency similarity; matches surface previous incidents, their resolution, and a link. Past lessons actively inform new investigations.

Architecture & privacy

Backend	Hono (Node), TypeScript, PostgreSQL via Prisma.
Auth	scrypt password hashing (node:crypto), opaque session tokens, per-IP rate limiting and abuse detection.
Webhooks	Public /w/:slug capture with optional signature verification; replay tooling for live debugging.
Deployment	Your own instance — you control the data plane and AI configuration.

Code: open source on GitHub. Ongoing work, issues and contributions welcome.