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; store after
5. Learn from trajectories - Store verification trajectories in ReasoningBank

Inputs/Outputs

Workflow

Phase 0: Configuration

Present three optional 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

Ask scope BEFORE extraction. No exceptions.

Phase 2: Claim Extraction

Sources:

Categories:

Also flag: Ambiguous, Misleading, Jargon-heavy

Phase 3: Triage

Present ALL claims upfront. User must see full scope before verification.

Display grouped by category with depth recommendations:

## Claims Found: 23

### Security (4 claims)
1. [MEDIUM] src/auth.ts:34 - "passwords hashed with bcrypt"
2. [DEEP] src/db.ts:89 - "SQL injection safe via parameterization"
...

Adjust depths? (Enter numbers to change, or 'continue')

Depth Definitions:

ARH pattern for responses: DIRECT_ANSWER (accept, proceed), RESEARCH_REQUEST (dispatch analysis), UNKNOWN (analyze, regenerate), SKIP (use defaults).

Phase 4: Parallel Verification

Check AgentDB BEFORE verifying. Store findings AFTER.

// Before: check existing
const existing = await agentdb.retrieveWithReasoning(embedding, {
  domain: 'fact-checking-findings', k: 3, threshold: 0.92
});
if (existing.memories[0]?.similarity > 0.92) return existing.memories[0].pattern;

// 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):

• SecurityAgent, CorrectnessAgent, PerformanceAgent
• ConcurrencyAgent, DocumentationAgent, HistoricalAgent, ConfigurationAgent

Phase 5: Verdicts

Every verdict MUST have concrete evidence. NO exceptions.

Phase 6: Report

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

Bibliography Formats:

Phase 6.5: Clarity Mode (if enabled)

Generate glossaries/key facts from verified claims (confidence > 0.7).

Targets: CLAUDE.md, GEMINI.md, AGENTS.md, *_AGENT.md, *_AI.md

Glossary Entry: - **[Term]**: [1-2 sentence definition]. [Usage context.]

Key Fact Categories: Architecture, Behavior, Integration, Error Handling, Performance

Update existing sections or append before --- separators.

Phase 7: Learning

Store trajectories in ReasoningBank:

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

Applications: depth prediction, strategy selection, ordering optimization, false positive reduction.

Phase 8: Fixes

NEVER apply fixes without explicit per-fix user approval.

1. Present implementation plan for non-verified claims
2. Show proposed change, ask approval
3. Apply approved fixes
4. Offer re-verification

Interruption Handling

Checkpoint to .fact-checking/state.json after each claim:

{
  "scope": "branch",
  "claims": [...],
  "completed": [0, 1, 2],
  "pending": [3, 4, 5],
  "findings": {...},
  "bibliography": [...]
}

Offer resume on next invocation.

### Security (2 claims)
1. [MEDIUM] src/auth/password.ts:34 - "passwords hashed with bcrypt"
2. [DEEP] src/auth/session.ts:78 - "session tokens cryptographically random"
...

# Fact-Checking Report
**Scope:** Branch feature/auth-refactor (12 commits)
**Verified:** 5 | **Refuted:** 1 | **Stale:** 1 | **Inconclusive:** 1

## Bibliography
[1] Code trace: src/auth/password.ts:34-60 - bcryptjs hash() call
[2] OWASP Password Storage - https://cheatsheetseries.owasp.org/...

## Implementation Plan
1. [ ] src/cache/store.ts:23 - TTL is 60s not 300s, update comment