Debugging Engine

Debugging Engine (State Machine–Driven Agentic Debugging Workflow) is an investigation kernel, not a chat agent.

Coding agents (Cursor, Claude Code, Copilot, Codex, …) drive it through a CLI or the Python library. The engine owns Case State, the Event Log, validation, projections, and Judge scheduling. It does not embed an LLM.

Why

• Investigation state is explicit (Case / Unknown / Hypothesis / Experiment / Evidence), not buried in chat
• A Judge schedules the next role and allowed events — agents advance the case, they don’t “find the answer” alone
• Experiments carry Verification Specs; evidence beats persuasion
• Same kernel for every coding agent via project skills

Install

uv tool install debugging-engine

Local checkout:

uv tool install --force .
# or
uv pip install -e ".[dev]"

Quick start

# Scaffold skills into the current project
debugging-engine --agent cursor   # or: claude, copilot, codex, all

# Describe the unknown
# (create issues/my-bug.md with symptoms + success criteria)

debugging-engine open issues/my-bug.md
debugging-engine next <case-id>
# … reason / edit outside the kernel …
debugging-engine submit <case-id> --events events.json
debugging-engine verify <case-id> <experiment-id>

Loop until RootCauseAccepted or escalate.

Scaffold & uninstall

debugging-engine --agent claude,cursor
debugging-engine --agent all
debugging-engine --agent cursor --force
debugging-engine --agent cursor --path /other/repo

debugging-engine --uninstall claude
debugging-engine --uninstall all --force
debugging-engine uninstall-cli    # uv tool uninstall debugging-engine

Empty agent skill directories (for example .agents/ or .claude/skills/) are removed when uninstall leaves them empty.

Skills:

• debugging-engine-investigate — general debugging
• debugging-engine-incident — production incidents
• debugging-engine-performance — latency / throughput / memory

CLI

debugging-engine open <issue.md>
debugging-engine next <case-id>
debugging-engine submit <case-id> --events events.json
debugging-engine verify <case-id> <experiment-id>
debugging-engine status|log|replay <case-id>
debugging-engine query <case-id> [slice]

debugging-engine demo       # offline stub investigation (temp fixture)
debugging-engine validate   # Phase 2 architectural scenarios (temp fixture)

Python API

from debugging_engine import Case, Engine

engine = Engine(repo_root=".")
case = Case.open(engine, "issues/my-bug.md")
task = case.next()
# case.submit([...]); case.verify(experiment_id)

Full surface: docs/api.md.

Specification

Debugging Engine v1.0.0 specification: docs/SPECIFICATION.md.

Repository layout

Development

uv pip install -e ".[dev]"
pytest
uv build
uv publish   # requires UV_PUBLISH_TOKEN / PyPI credentials