fact-checking

Invariant Principles

1. Claims are hypotheses - Every claim requires empirical evidence before verdict
2. Evidence before verdict - No verdict without traceable, citable proof
3. User controls scope - User selects scope and approves all fixes
4. Deduplicate findings - Check AgentDB before verifying to avoid redundant work
5. Learn from trajectories - Store verification trajectories in ReasoningBank for improvement

Inputs

Outputs

Workflow

Phase 0: Configuration

Present modes (default: all enabled):

• Missing Facts Detection: gaps where claims lack critical context
• Extraneous Info Detection: redundant/LLM-style over-commenting
• Clarity Mode: generate glossaries for AI config files

Autonomous mode detected ("Mode: AUTONOMOUS")? Enable all automatically.

Phase 1: Scope Selection

<RULE>Ask scope BEFORE extraction. No exceptions.</RULE>

Phase 2: Claim Extraction

Sources: Comments (//, #, /* */), docstrings, markdown, commits, PR descriptions, naming (validateX, safeX, ensureX)

Categories:

Also flag: Ambiguous, Misleading, Jargon-heavy

Phase 3: Triage

<RULE>Present ALL claims upfront. User must see full scope before verification.</RULE>

Display grouped by category with depth recommendations:

• Shallow: read code, reason about behavior
• Medium: trace execution paths, analyze control flow
• Deep: execute tests, run benchmarks, instrument code

ARH pattern for responses:

• DIRECT_ANSWER: accept adjustments, proceed
• RESEARCH_REQUEST: dispatch analysis subagent
• UNKNOWN: analyze complexity, regenerate recommendations
• SKIP: use defaults

Phase 4: Parallel Verification

<RULE>Check AgentDB BEFORE verifying. Store findings AFTER.</RULE>

// Before: check existing
const existing = await agentdb.retrieveWithReasoning(embedding, {
  domain: 'fact-checking-findings', k: 3, threshold: 0.92
});

// After: store finding
await agentdb.insertPattern({
  type: 'verification-finding',
  domain: 'fact-checking-findings',
  pattern_data: { claim, location, verdict, evidence, sources }
});

Spawn category agents via swarm-orchestration (hierarchical topology).

Phase 5: Verdicts

<RULE>Every verdict MUST have concrete evidence. NO exceptions.</RULE>

Phase 6: Report

Sections: Header, Summary, Findings by Category, Bibliography, Implementation Plan

Bibliography formats:

• Code trace: file:lines - finding
• Test: command - result
• Web: Title - URL - "excerpt"
• Git: commit/issue - finding

Phase 6.5: Clarity Mode (if enabled)

Generate glossaries/key facts from verified claims. Update AI config files (CLAUDE.md, GEMINI.md, AGENTS.md).

Phase 7: Learning

Store trajectories in ReasoningBank:

await reasoningBank.insertPattern({
  type: 'verification-trajectory',
  pattern: { claimText, depthUsed, verdict, timeSpent, evidenceQuality }
});

Phase 8: Fixes

<RULE>NEVER apply fixes without explicit per-fix user approval.</RULE>

Present plan, get approval per fix, apply, offer re-verification.

Interruption

Checkpoint to .fact-checking/state.json after each claim. Offer resume on next invocation.

If NO to ANY: STOP and fix.

Self-Check

Before completing:

• Configuration wizard completed (or autonomous mode active)
• Scope explicitly selected by user
• ALL claims presented for triage before verification
• Each verdict has concrete, citable evidence
• AgentDB checked before verification, updated after
• Bibliography includes sources for all verdicts
• Trajectories stored in ReasoningBank
• Fixes await explicit per-fix user approval

If ANY unchecked: STOP and fix.