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.

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:

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 allowe

... View full README on GitHub