github.com/mechana-ai/orion-protocol
AI agents almost universally do not debug in the true sense of debugging. They loop through pattern match solutions looking solely at your source code. With many types of bugs, this is an anti-pattern.
ORION PROTOCOL breaks the cycle by forcing agents into empirical mode — probe the running system, record what actually happens when the code runs, discard theories that don't survive contact with reality. Science.
If you have used AI to code for long stretches, surely you have encountered the pattern of AI looping through fixes that don't work. AI doesn't clean up the failed attempts, and a layer of 'code barnacles' accrete so densely that the code becomes impossible to follow.
The only option is often a git restore and to take a walk.
Watching this pattern unfold too often, we developed ORION PROTOCOL.
We realized AI was not really debugging anything in these loops. It was pattern matching source code fixes. One after another. Sometimes it works. Sometimes, it doesn't work, because the problem is out of the domain of the source code itself.
It occurs during RUNTIME.
So there is nothing scientific — scientific method scientific — about that approach to debugging.
So, we pointed AI back to school. Francis Bacon. The proto-science of 1620.
Telling an AI "you are a senior engineer" is identity shifting — it's affirmations for LLMs. It doesn't change how the model reasons. ORION uses epistemic shifting instead: it moves the LLM into a different theory of knowledge entirely.
The protocol points the agent to Francis Bacon's Novum Organum (1620) and his distinction between anticipation of nature (reasoning from existing notions — fast, fluent, wrong as often as right) and interpretation of nature (reasoning from the thing itself, by direct examination). The strong writing of Bacon overrides the maladaptation of LLMs to mistake passive code review for actual debugging.
By referencing a 400-year-old epistemological framework, the LLM is state-shocked into an entirely new context — a highly specific, sparsely populated cluster of its training data. The trance breaks. The agent starts to debug.
Bacon's terms map cleanly onto software:
Because these concepts map so cleanly, agents are left with no room to return to low-effort semantic matching. They are forced to work through the empirical loop: theory, observation, new theory.
A standalone markdown file. Copy it into your project, point your AI to it, and say Implement ORION PROTOCOL. No dependencies, no installation. Works with any AI coding agent that reads markdown.
The protocol defines an 8-step empirical procedure: state the failure, run a history pass, state one hypothesis, choose probes, read the probes, record observations, update, and stop conditions. It names Bacon's four Idols (Tribe, Cave, Marketplace, Theatre) as cognitive biases to watch for when debugging drifts.
A structured debugging ledger for more stubborn or complex problems. Separates confirmed observations from theories in a SQLite database. Tracks failed attempts so agents do not recycle dead ideas. Names cognitive biases across sessions. Integrates with any MCP-compatible client.
pip install git+https://github.com/mechana-ai/orion-protocol.git{
"mcpServers": {
"historia-naturalis": {
"command": "historia-naturalis"
}
}
}Free for individuals. Teams of 2+ require a commercial license.
← mechana.ai