inquisitor

<div align="center">

# inquisitor

**Hypothesis-driven problem solving for AI agents**
Probe · Falsify · Escalate — never overcomplicate, never blind-retry

[![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2?style=flat-square)](https://modelcontextprotocol.io)
[![uv](https://img.shields.io/badge/uv-package-6A3C8E?style=flat-square)](https://github.com/astral-sh/uv)
[![CI](https://img.shields.io/github/actions/workflow/status/1111111111111111111114oLvT2/inquisitor/ci.yml?style=flat-square&label=CI)](https://github.com/1111111111111111111114oLvT2/inquisitor/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)]()

</div>

<!-- mcp-name: io.github.1111111111111111111114oLvT2/inquisitor -->

## Overview

**inquisitor** makes AI agents solve problems the way a chess engine plays chess: it cannot explore every branch, so it **estimates complexity first, prunes paths that add no information, and spends its search budget only where the problem actually is**.

It ships as two coordinated layers:

- **MCP server** (`inquisitor-mcp`) — the engine. Web search, project analysis, code tracing, project scaffolding, and a persistent investigation state machine. Works with any MCP-compatible agent: OpenCode, Claude Code, Claude Desktop, Cursor.
- **Agent skill** (`skills/inquisitor/SKILL.md`) — the behavioral layer. Injects the probe-and-gate loop, the pruning rules, and the full methodology into the agent's reasoning.

The method is not invented here — it is assembled from primary sources: Newton's Analysis→Synthesis skeleton, hardened with the scientific method's own defenses against wrong assumptions (falsification, strong inference, competing-hypotheses analysis, anti-fixation reframes, pre-mortems) and constrained by engineering discipline (NASA/JPL's Power of Ten, surgical-change guidelines, the minimalism ladder). Every source is cited in [Foundations](#foundations).

> Web search, codebase scans, and code tracing are **tools invoked when local evidence is insufficient — never mandatory rituals**.

---

## How it decides

Depth is an **output, not a label**. An LLM's up-front difficulty guess is its least reliable signal — poorly calibrated, and biased to under-rate exactly the hard problems that matter. So inquisitor never classifies a problem before understanding it: it runs a cheap **probe** (the single cheapest action that could confirm or kill the best current hypothesis), and the probe's *result* — never the prediction — sets the depth:

```mermaid
flowchart TD
    P([Problem]) --> F["FRAME<br/>done = ? · must not break = ?"]
    F --> D{"delegate?<br/>a specialist skill<br/>owns this"}
    D -->|yes| SK["hand off — /tdd,<br/>/code-review, ..."]
    D -->|no| PR["PROBE<br/>cheapest action that could confirm<br/>or kill the best hypothesis"]
    PR -->|"obvious, local"| SH["<b>Shallow</b><br/>fix → verify<br/><i>no ceremony</i>"]
    PR -->|"clear single-<br/>component cause"| ST["<b>Standard</b><br/>frame → minimal evidence<br/>→ fix → verify"]
    PR -->|"root cause unknown,<br/>multi-component"| DE["<b>Deep</b> — Newton 7-phase:<br/>DEFINE → AXIOMS → ANALYSIS →<br/>EXPERIMENT → SYNTHESIS →<br/>VALIDATE → QUERY<br/><i>+ session tracking as memory</i>"]

    SH -.->|"gate trigger /<br/>failed fix / low confidence"| ST
    ST -.->|"gate only raises depth —<br/>never lowers"| DE
```

**Escalation is enforced, not just allowed.** The probe is only a starting point: objective gate triggers (touching infra/deploy/routing/config, auth/security, data migrations, multi-file fixes, prod-only symptoms) force a minimum depth regardless of how "clear" the problem feels, and a 3-question confidence check (read the runtime path? can name the runtime signal? verified the platform assumption?) bumps the depth up per unanswered question. Downgrades need cited evidence, never a feeling. **Inflated ceremony is not allowed either** — a 7-phase investigation of a typo is as wrong as a blind guess at a race condition.

**Retry is never blind.** "Loop until it passes" agents (the Ralph-loop pattern) have persistence but no memory: on failure they revert, flush, and re-roll — the same wrong idea, retried with fresh confidence. Inquisitor keeps a failure ledger instead: every dead hypothesis is recorded with the evidence that killed it, every retry must name what is different and why that changes the outcome, and two dead hypotheses from the same family force a *reframe* — re-audit an assumption, invert the question, widen the system boundary — never a third attempt at the same idea. Persistence with memory, creativity on evidence.

---

## Foundations

Each rule in the method traces to a primary source. The left column is the citation; the right column is the exact mechanism inquisitor takes from it.

### The scientific method

| Source | Mechanism adopted |
|--------|-------------------|
| Isaac Newton, [*Opticks*, Query 31](https://www.gutenberg.org/ebooks/33504) (1704) | The investigation skeleton: Analysis before Synthesis — define, decompose, experiment, only then reconstruct — and closing with open Queries instead of false certainty. *Hypotheses non fingo.* |
| T.C. Chamberlin, [*The Method of Multiple Working Hypotheses*](https://www.science.org/doi/10.1126/science.148.3671.754), Science (1890) | Hold at least two rival explanations at all times; a single hypothesis turns every subsequent observation into confirmation. |
| Abraham Luchins, *Mechanization in Problem Solving* (1942) — the [Einstellung effect](https://en.wikipedia.org/wiki/Einstellung_effect) | The failure ledger's trigger: repeating a familiar approach after it stopped working is a measurable fixation, and the cure is a forced reframe, not another attempt. |
| Karl Popper, [*The Logic of Scientific Discovery*](https://en.wikipedia.org/wiki/The_Logic_of_Scientific_Discovery) (1959) | Falsify first: for the leading hypothesis, name the observation that would disprove it and hunt for that observation before anything else. |
| John Platt, [*Strong Inference*](https://www.science.org/doi/10.1126/science.146.3642.347), Science (1964) | Design the experiment that *excludes* a hypothesis, not the one that corroborates the favorite — discriminating tests over confirming tests. |
| Richards J. Heuer, [*Psychology of Intelligence Analysis*](https://www.cia.gov/resources/csi/books-monographs/psychology-of-intelligence-analysis-2/), CIA (1999) | Analysis of Competing Hypotheses: rank hypotheses by the evidence *inconsistent* with each — confirming evidence is cheap and usually fits several at once. |
| Gary Klein, [*Performing a Project Premortem*](https://hbr.org/2007/09/performing-a-project-premortem), Harvard Business Review (2007) | Before shipping: assume the fix is live and the problem still happens — name the likeliest reason and probe it now. |

### Engineering discipline

| Source | Mechanism adopted |
|--------|-------------------|
| Gerard J. Holzmann (NASA/JPL), [*The Power of Ten: Rules for Developing Safety-Critical Code*](https://spinroot.com/gerard/pdf/P10.pdf) (2006) | The P10 template: a rule set small enough to remember and strict enough to check mechanically. |
| [Andrej Karpathy's LLM coding guidelines](https://github.com/forrestchang/andrej-karpathy-skills) (2025) | Think before coding · simplicity first · surgical changes · goal-driven execution. |
| [Ponytail decision ladder](https://github.com/dietrichgebert/ponytail) | YAGNI → reuse → stdlib → native platform → installed dependency → one line → minimum code that works. |

---

## Installation

Requires [uv](https://github.com/astral-sh/uv) and Python 3.12+.

### Claude Code — plugin install (recommended)

inquisitor ships as a [Claude Code plugin](https://code.claude.com/docs/en/plugins) that installs **both the skill and the MCP server** — no cloning, no editing absolute paths, no manual symlink.

From within Claude Code, first add the marketplace:

```
/plugin marketplace add 1111111111111111111114oLvT2/inquisitor
```

Then install the plugin:

```
/plugin install inquisitor@inquisitor
```

That's it. The plugin bundles the `inquisitor-mcp` server (registered automatically via `${CLAUDE_PLUGIN_ROOT}`) and the `inquisitor` skill. `uv` syncs the server's dependencies on first launch. Update later with `/plugin marketplace update inquisitor`.

> Prefer to point at a local checkout instead of GitHub? `/plugin marketplace add /path/to/inquisitor` works too.

For **OpenCode** and **Claude Desktop** (which don't use Claude Code plugins), or for a manual Claude Code setup, use the steps below.

### Step 1 — Get the server

**Option A — no clone (recommended).** Once published to PyPI, `uvx` fetches and runs it on demand — no clone, no absolute paths:

```bash
uvx inquisitor-mcp   # prints a ready message and waits for a client — Ctrl+C to exit
```

You'll reference `uvx inquisitor-mcp` directly in the config below.

**Option B — from a checkout** (for local development, or before the PyPI release):

```bash
git clone https://github.com/1111111111111111111114oLvT2/inquisitor.git ~/tools/inquisitor
cd ~/tools/inquisitor
uv sync
```

> The clone path is up to you — just use the **same absolute path** in the config below. `~` does not expand inside JSON config files, so write the full path (e.g. `/home/you/tools/inquisitor`).

You do **not** run the server manually. It's a stdio MCP server: your agent spawns and manages it automatically. (If you run it by hand it prints a ready message on stderr and waits silently — that's normal.)

### Step 2 — Register the MCP server with your agent

**OpenCode** — add to `~/.config/opencode/opencode.json` (global) or `./opencode.json` (per-project):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "inquisitor": {
      "type": "local",
      "command": ["uvx", "inquisitor-