Introduction

dont is a command-line tool for autonomous LLM harnesses. Its job is narrow and opinionated: stop an agent from turning ungrounded text into asserted project truth.

This book explains why the problem exists, how dont solves it, and where to find detailed specs and research.

In this repo’s workflow (not required to understand or use dont):

• wai helps track workflow and design intent
• bd tracks concrete work
• dont governs epistemic discipline

This book is the reader-friendly front door for the project. It does not replace the fuller OpenSpec decomposition or the archived monolithic draft in wai research. Instead, it explains the problem the tool is meant to solve and points to the deeper source material in the repository, especially the tracked research notes under .wai/projects/dont/research/. These notes are part of the project’s workflow and research record managed with wai.

Read this book if you want to know

• what dont is for
• why ordinary “please double-check yourself” prompting is not enough
• how to ground repository facts with dont ground, repository-relative locators, and dont trace
• how the project’s research maps onto the proposed tool

Key sources

(Note: External links point to the main branch of the repository.)

• OpenSpec change specs (openspec/changes/*/specs/)
• Research: forcing doubt in minds and machines
• Research: designing doubt into AI interaction
• Repository README

Getting Started with dont

Prerequisites

Build dont from source and install it to your PATH:

git clone https://github.com/charly-vibes/dont.git
cd dont
cargo install --path .

Verify:

dont --version

When to reach for dont

The trigger is a thought that starts with “I think…”, “I believe…”, or “I’m assuming…” — combined with the fact that you haven’t verified it yet, and that being wrong would cost you time.

If you find yourself holding two competing explanations for a bug, that’s the clearest signal. dont gives those competing explanations a name, lets you track evidence for each, and forces you to resolve them before moving on.

A real session

You’re debugging a write-loss bug. Writes succeed (no errors returned) but data disappears after process restart. You have two theories.

First time? Initialize first:

dont init

Returning session? Orient first:

dont prime

This shows what claims are currently doubted or unverified — your open questions from the last session. If the store is clean, it exits 0 silently. If something is doubted, it exits 1 and tells you what to resolve first.

Step 1: Record the claim you’re investigating

dont conclude "CozoDb flushes writes lazily, causing data loss on unclean shutdown"
# → claim:01ABC123...

Step 2: Add a competing hypothesis

You’re not sure. Connection pool exhaustion could also cause silent write drops before any flush happens.

dont hypothesis add claim:01ABC123... --text "Connection pool exhaustion silently drops writes before flush"
# hypothesis added at index 0

Step 3: Gather evidence

You find the flush behavior in source:

dont flag claim:01ABC123... --file src/store.rs --lines 47-62

You check connection pool behavior and find it refutes the competing hypothesis. Hypotheses are referenced by 0-based index:

dont hypothesis assess claim:01ABC123... 0 --refuting src/pool.rs

Step 4: Confirm

Flagging evidence (dont flag) transitions the claim from unverified to verified. dont show lets you confirm the new state:

dont show claim:01ABC123...

Status is verified. The claim is grounded and the competing hypothesis is marked refuted.

Step 5: Lock when mature

dont lock requires ≥ 3 assessed hypotheses and ≥ 2 independent evidence sources. This tutorial used one hypothesis for brevity — see Competing hypotheses and atoms for the full lock pattern.

dont lock claim:01ABC123...

Lifecycle summary

Fast path: one-shot grounding

When you already have both the claim and the evidence in hand:

dont ground "The crate exposes a test recipe" --file justfile --lines 12-13

This concludes and verifies in a single command.

Competing hypotheses and atoms

When you have more than one explanation

The most valuable use of dont is when you’re mid-investigation with two or more competing explanations for something you don’t yet understand.

dont hypothesis lets you record those competing explanations under a single claim and assess each one as evidence comes in. This prevents the common failure: you go looking for evidence of hypothesis A, find something that looks plausible, and declare it confirmed — without ever seriously checking hypothesis B.

Hypotheses: step by step

1. State the claim (the thing you’re investigating):

dont conclude "API calls to the pricing endpoint are timing out intermittently"
# → claim-abc

2. Add competing hypotheses:

You can add hypotheses at any point before locking — before or after gathering initial evidence. Each hypothesis is assigned a 0-based index in the order it was added.

dont hypothesis add claim-abc --text "The upstream rate limit is being hit on burst traffic"
# → index 0

dont hypothesis add claim-abc --text "A database lock contention slows queries beyond the client timeout"
# → index 1

dont hypothesis add claim-abc --text "TLS handshake overhead on cold connections is the bottleneck"
# → index 2

3. Assess each with evidence:

Both dont flag calls and --supporting assessments count as independent evidence sources toward the lockability threshold.

Hypotheses are referenced by their 0-based index (use dont show <claim-id> to see indices).

# Found rate limit logs — supports hypothesis 0
dont hypothesis assess claim-abc 0 --supporting logs/api-2026-05-07.log --lines 144-151

# Checked DB profiler — no long-running queries during timeout windows
dont hypothesis assess claim-abc 1 --refuting reports/db-profile.txt

# TLS session reuse is enabled — refuted
dont hypothesis assess claim-abc 2 --refuting src/client.rs --lines 88-94

4. Flag the surviving hypothesis as evidence for the claim:

dont flag claim-abc --file logs/api-2026-05-07.log --lines 144-151

5. Lock when mature (requires ≥ 3 assessed hypotheses + ≥ 2 independent evidence sources):

dont lock claim-abc

Atoms: when a claim has multiple independently checkable parts

Sometimes a single claim is composite — it holds if and only if several sub-conditions hold. dont atom lets you decompose it.

Example: “The API client correctly handles all three authentication scenarios” might require:

• evidence that bearer token auth succeeds
• evidence that expired token returns 401 and triggers refresh
• evidence that missing credentials return 403 without retry

dont conclude "The API client correctly handles all three authentication scenarios"
# → claim-xyz

dont atom define claim-xyz --text "Bearer token auth returns 200 on valid credentials"
# → index 0

dont atom define claim-xyz --text "Expired token triggers refresh and retries the request"
# → index 1

dont atom define claim-xyz --text "Missing credentials return 403 without retry"
# → index 2

Dismiss each atom as you verify it, using its 0-based index:

dont atom dismiss claim-xyz 0 --evidence tests/auth_test.rs --lines 12-28
dont atom dismiss claim-xyz 1 --evidence tests/auth_test.rs --lines 31-55
dont atom dismiss claim-xyz 2 --evidence tests/auth_test.rs --lines 58-74

Using dont as an LLM agent

Core pattern: conclude before asserting

Every time you are about to write something as established fact — in a reply, in a command, in a plan — and you haven’t verified it yet, use dont conclude first.

Then verify it. Then dont flag with the evidence.

This is the only discipline that matters. Everything else follows.

Trigger conditions

Use dont conclude when you find yourself producing text like:

• “The store.rs file handles connection pooling”
• “This function is called only from the test harness”
• “The API rate limit is 500 requests per minute”
• “I believe the bug is in the flush path, not the connection path”

Each of these is an unverified claim. Record it before you act on it.

Do not use dont for

• Things you already verified before stating them (just state them)
• Universal facts not specific to this codebase (“Rust is memory-safe”)
• Housekeeping claims that will never be doubted (“the commit message is in conventional commits format”)

The overhead is worth it when being wrong would send you down a wrong path. Apply it selectively.

Session start

Always run dont prime before beginning investigation work:

dont prime

• If it exits 0: no open doubted claims. Proceed.
• If it exits 1: there are doubted claims from a previous session. Resolve them before introducing new claims.

This is your orientation step. It is not just a CI gate.

Full pattern for investigating a bug

# 1. Orient
dont prime

# 2. State what you believe (before you verify)
dont conclude "The write loss is caused by lazy flush in CozoDb"
# → claim-abc

# 3. Add competing explanations (before you go looking for evidence)
dont hypothesis add claim-abc --text "Connection pool exhaustion drops writes silently"
dont hypothesis add claim-abc --text "OS buffer not flushed on SIGTERM"

# 4. Find evidence — file + line span
dont flag claim-abc --file src/store.rs --lines 47-62

# 5. Assess hypotheses as evidence comes in (IDX is 0-based integer)
dont hypothesis assess claim-abc 0 --refuting src/pool.rs --lines 88-103
dont hypothesis assess claim-abc 1 --supporting src/shutdown.rs --lines 12-18

# 6. Check status
dont show claim-abc

What counts as evidence

Prefer repository-relative locators:

--file src/store.rs --lines 47-62       # file + line span
--file justfile --lines 12-13           # any text file in the repo
--file docs/spec.md --anchor "Flush"    # anchor within a file

External URLs are accepted when the evidence lives outside the repo:

--evidence https://docs.example.com/api#rate-limits

Quick reference

dont prime                              # orient: any doubted claims?
dont conclude "..."                     # register an unverified claim
dont ground "..." --file F --lines N-M # register and verify in one step
dont flag <id> --file F --lines N-M    # attach evidence to existing claim
dont hypothesis add <id> --text "..."  # add a competing explanation
dont hypothesis assess <id> <idx> --refuting <path> [--lines N-M]  # idx is 0-based integer
dont show <id>                         # check current status
dont trust <id> --reason "..."         # mark as doubted (blocks prime)
dont ignore <id> --reason "..."        # set aside a claim (scope change, no longer relevant)
dont lock <id>                         # freeze a mature verified claim
dont list                              # all claims and their statuses
dont trace <id>                        # explain why a claim is blocked

Why dont exists

The problem

Takeaway: Fluency is not epistemic discipline — and that distinction has real consequences in autonomous workflows.

Large language models are good at producing fluent answers, but fluency is not the same thing as epistemic discipline.

Once a model has started down a line of reasoning, it often tends to elaborate on that line instead of questioning it. In practice, this means an autonomous agent can:

• state a claim too early
• defend the claim after weak checking
• fold the claim into project memory or downstream actions
• create a trail of confident but poorly grounded work

The core idea behind dont is that this failure mode should not be handled as a style problem. It should be handled as a tooling problem.

The research-backed claim

Takeaway: Asking an LLM to reconsider is usually weaker than forcing it through an external verification path.

The research corpus in this repository points to a consistent conclusion:

1. LLMs do not reliably self-correct just because they are asked to reconsider.
2. Better results usually come from external checks such as retrieval, tests, verifiers, or independent critics.
3. Durable human institutions solve similar problems by separating assertion from evaluation.

So the design stance of dont is simple:

Do not let an agent assert what it has not yet grounded.

What dont does

Takeaway: dont turns epistemic caution into explicit tool-mediated state transitions.

dont is a forcing function for autonomous LLM harnesses.

It gives the model a mechanical path between “I want to say this” and “this is now grounded enough to keep.”

Instead of letting every plausible sentence become accepted project state, dont introduces explicit transitions such as:

• conclude a claim
• define a term
• trust with a reason
• flag with evidence
• move entities through statuses like unverified, doubted, verified, or locked

The point is not to make the model sound cautious. The point is to make the workflow itself require justification.

Why a tool instead of a prompt

Takeaway: A tool enforces process outside the model’s own judgment; a prompt merely asks the same model to judge itself.

Prompting alone is weak because the same model that produced the claim is often asked to judge its own claim in the same context.

The draft spec and research notes both argue for the opposite pattern:

• make claims explicit
• record state changes
• surface unmet conditions as actionable refusals
• use fresh-context verification paths when independence matters

That is why dont is proposed as a peer CLI tool, not just a prompt template.

The role of dont in a harness

These companion tools reflect the surrounding workflow used in this repository; they are helpful context, not prerequisites for understanding dont.

A harness can use three different kinds of support:

• memory tools to remember what happened
• workflow tools to know what stage of work is happening
• epistemic tools to control what is allowed to count as grounded

dont is the third category.

It is meant to sit beside workflow and memory tools, but remain independent from them. Its concern is narrower: claims, terms, evidence, rules, and the right to assert.

Epistemic design choices

Grounding as a lifecycle shortcut

The underlying lifecycle for any claim in dont is:

1. conclude — introduce an unverified claim
2. trust — register doubt
3. flag — verify with evidence
4. lock — freeze a mature verified claim

dont ground is a convenience command that composes these steps. It is not a separate epistemic model; it records the claim and verifies it in one invocation while ensuring normal event history and status rules still apply.

Preference for repository-relative locators

dont prefers repository-relative locators (using --file and --lines) over opaque absolute file:// URIs. This is an intentional design choice to ensure that evidence remains:

• Readable: locators are easy for humans and agents to audit.
• Auditable: the evidence is scoped to the project root.
• Secure: absolute paths, .. traversal, and symlink escapes are refused to prevent project-evidence leaks.

Non-goals

dont is not meant to be:

• a general ontology editor
• a replacement for external validators or retrieval systems
• a memory system
• a workflow planner
• a magical truth machine

It is a guardrail and protocol layer.

A short example

An agent concludes: “The API rate limit is 500 requests per minute.”

Without dont, that sentence can quietly become accepted project state just because it sounds plausible.

With dont, the claim is recorded as unverified via dont conclude. Any attempt to promote or rely on it without evidence produces a structured refusal — one that tells the agent exactly what to do next: gather evidence, use dont flag, or request independent verification. Only after that grounding step can the claim earn a more trusted status.

That is the point of dont: not better-sounding caution, but enforced epistemic process.

Read next

• Research basis

Repository-grounding workflow

dont can act as a sidecar for any investigation session: claims you record are persisted to the store and survive context resets. Use it when you want repository facts to outlast a single chat session.

This page covers the three most common patterns: fast single-shot grounding, attaching evidence with repository-relative locators, and diagnosing blockers with dont trace.

Fast path: ground a documented fact

When the claim and repository evidence are both in hand, use dont ground:

dont ground "The project builds docs with mdBook" --file justfile --lines 48-49

Use repository-relative locators

For evidence inside the current project, use --file with an optional line span or anchor:

dont ground "The crate exposes a test recipe" --file justfile --lines 12-13
dont flag <id> --file src/main.rs --lines 188-205 --anchor "Ground"

Plain URI evidence is still supported for external sources:

dont flag <id> --evidence https://example.org/source

Diagnose blockers with trace

If show, why, or prime reports stale dependencies, unresolved terms, or blocker labels without enough context, run:

dont trace <entity-id>

trace reports the blocker path so you can see which dependency or support relation needs attention before trying to verify or lock the claim.

Enforcement model

dont is designed so that there is no --no-verify equivalent — no flag that lets a caller skip the verification gates. This page explains why, what the actual gates are, and how to wire them into your toolchain.

Why there is no bypass flag

Git’s --no-verify works by skipping hook scripts — side-car processes that live outside the binary. Because they’re external, they can be bypassed.

dont’s gates live inside the binary:

• State transitions are exhaustive match arms in Rust. The code for a forbidden transition (Doubted → Locked) simply doesn’t exist.
• The dependency integrity check runs in-process before any verification is accepted. There is no code path around it.
• dont prime is designed to be the terminal check — it exits 1 on doubted claims, regardless of project mode.

An agent or user can always choose not to call dont, but they cannot call it while bypassing its rules.

The fundamental limit: this infrastructure makes it harder to accidentally skip the check — it does not make skipping impossible. An agent that never calls dont is invisible to these gates. The discipline works only when agents register claims as they make them (see the grounding workflow).

In-binary gates

1. State machine (src/model.rs)

All transitions are exhaustive matches. The only path to Locked is Unverified → Verified → Locked. Doubted → Locked has no match arm.

2. Always-strict rules (src/rules/mod.rs)

Three rules are hardcoded to Strict severity before any config lookup:

These cannot be downgraded to warnings via project config.

3. Dependency integrity gate

Before a claim can be verified with dont flag (read: “don’t flag this as a concern”), dependency_gate_unmet_clauses() walks all dependencies. If any are Unverified or Doubted, the command emits a structured refusal and exits 1.

4. Hedge filter

dont trust and dont ignore reject assertions that contain hedge language ("I think", "maybe", "probably", etc.). The default list is compiled in; config can only extend it, never replace it.

5. dont prime — orientation and terminal gate

dont prime has two roles:

Orientation — run it at the start of a session to see what’s doubted or unverified. It always prints the project status summary (mode, counts by status, and any blocking entities). When the store is clean it exits 0.

Terminal gate — run it at the end (CI, pre-commit, agent stop hook) to confirm nothing was left unresolved. It exits 1 if any claim is Doubted, regardless of project mode.

Projects initialize in permissive mode by default (pass --strict to dont init to start in strict mode). Unverified claims are allowed in permissive mode (where warnings replace errors for most rules); doubted claims are always blocking regardless of mode.

6. Lockability rule

To lock a verified claim you need ≥ 3 assessed hypotheses and ≥ 2 independent evidence sources. This gate is enforced in-code inside the dont lock handler and cannot be bypassed — dont lock exits 1 if the gate is unmet, regardless of project mode or rule-engine config. (The lockable rule engine severity defaults to Warn so it does not block non-lock operations in the background; the hard enforcement is the in-command gate, not the background rule engine.)

Hook infrastructure

The same dont prime check runs at three points in the development cycle.

Git (prek pre-commit)

prek.toml includes a local hook that runs just check-claims (which runs dont prime) before every commit. (prek is a pre-commit hook runner — install it and run prek install to activate hooks.)

[[repos]]
repo = "local"
hooks = [
  { id = "dont-prime", name = "dont: block doubted claims",
    entry = "just check-claims", language = "system",
    pass_filenames = false, always_run = true },
]

If any claim is Doubted, the commit is rejected. Run prek install after editing prek.toml to activate the hook.

Claude Code / agentic tools

Add a Stop hook to .claude/settings.local.json so the agent surfaces doubted claims at the end of every session:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "just check-claims" }]
      }
    ]
  }
}

When dont prime exits 1, Claude Code displays the output as an error — a signal that the session ended with unresolved doubt. When claims are clean it exits 0 (output is still produced but not treated as an error by Claude Code).

CI

just ci calls just check-claims, which calls dont prime. A doubted claim fails the pipeline. See .github/workflows/ci.yml.

Research basis

• LLMs do not reliably self-correct in the same context that produced a claim.
• External signals such as evidence, tests, and independent critics are stronger.
• dont translates those conclusions into an explicit claim-handling protocol.

This page explains which research conclusions most directly shaped the design.

The documentation site is grounded in two main source categories in this repository:

• the OpenSpec change specs under openspec/changes/*/specs/, together with the archived monolithic draft preserved in wai research
• the tracked research artifacts under .wai/projects/dont/research/, especially the long-form syntheses on why LLMs defend prior outputs and how institutions force better verification

Main conclusions carried into the tool design

1. In-context self-correction is weak

The research summary argues that models often rationalize earlier answers instead of reliably inspecting them. Asking the same model, in the same context, to “be more critical” often produces better-sounding prose rather than better epistemic behavior.^{1 2}

This motivates dont’s refusal-oriented design: the system should block or route unsupported assertions instead of merely asking for a nicer explanation.

2. External signals are stronger than introspection

The strongest correction patterns in the cited literature depend on something outside the initial generation stream.¹

• retrieved evidence
• tests or executable checks
• trained verifiers
• independent critics or clean-context retries

This is why the spec emphasizes evidence, explicit remediation, and spawn-style verification requests instead of plain self-reflection.

3. Institutions solve this with structure

The research notes compare LLM verification failures to long-studied human failures in science, law, medicine, and engineering. Across those domains, reliability improves when systems enforce the following patterns^{1 2}:

• separation between generator and evaluator
• explicit burden of proof
• auditable state transitions
• procedures for challenge, review, and lock-in

dont translates that pattern into a CLI protocol for agents.

How this maps into the spec set

The current OpenSpec decomposition turns those conclusions into concrete design choices:

• a forcing-function CLI with a narrow role
• append-only history instead of silent rewrite
• explicit claim and term entities
• status transitions rather than implicit confidence
• refusal messages that tell the agent what to do next
• clean-context verification hooks when independent checking matters

Traceability

For deeper reading, start here:

• OpenSpec change specs (openspec/changes/*/specs/)
• Research: forcing doubt in minds and machines
• Research: designing doubt into AI interaction

Limits of this page

This page is a synthesis, not the full literature review. It is meant to explain why the project exists, not to replace the source documents.

1. Research: forcing doubt in minds and machines ↩ ↩2 ↩3

2. Research: designing doubt into AI interaction ↩ ↩2

Implementation status

dont has a working Rust implementation. This page summarises what is currently built, what is still in progress, and how the code maps to the OpenSpec specs.

What is implemented

All core lifecycle commands are functional:

The --json flag is available on all commands for machine-readable (Envelope-format) output.

How it maps to specs

The implementation is decomposed across OpenSpec specs in openspec/specs/. Key mappings:

See Sources and status for the full source map.

What is not yet built

• dont import (LinkML import surface) — spec exists in openspec/specs/dont-linkml-import
• MCP interface — spec exists in openspec/specs/dont-mcp-interface
• Spawn protocol — spec exists in openspec/specs/dont-spawn-protocol
• Completions (shell tab-completion) — wired up but not fully populated

Sources and status

This documentation site is an overview, not the project’s only source of truth.

What each source is for

• This mdBook (docs/) gives a reader-friendly explanation of the project’s purpose and research basis.
• The OpenSpec change specs are the detailed design documents for the tool’s capabilities, decomposed by feature area.
• Tracked research notes capture the reasoning and source synthesis behind the project’s design, including the archived monolithic draft.
• OpenSpec is the structured specification workspace with top-level specs and capability-focused change proposals.

Current project status

dont has a working Rust implementation with an active CLI surface. The repository contains:

• a functional implementation (src/)
• OpenSpec change specs for planned capabilities (openspec/changes/*/specs/)
• top-level formal specs (openspec/specs/)
• tracked research artifacts explaining the design rationale (.wai/projects/dont/research/)
• this mdBook documentation (docs/)

This book should be read as:

• an introduction to the project
• a guide to why the tool is designed this way
• a pointer to the more detailed project artifacts

How to read the project

If you are new here, read in this order:

1. this book for the overview
2. openspec/changes/*/specs/ for the detailed capability-by-capability design
3. .wai/projects/dont/research/ for the justification, research trail, and archived monolithic draft
4. openspec/ for the broader structured specification workspace

Important distinction

The mdBook explains the project in narrative form.

The OpenSpec change specs and related artifacts define the project more precisely.

The .wai research artifacts explain why those design choices were made.

Specs

The OpenSpec specs define dont’s capabilities precisely and are the authoritative source for implementation decisions. They live in openspec/specs/ in the repository.

Core specs

Interface specs

Evidence and grounding specs

Rule engine specs

Infrastructure specs

Future / in-progress specs