fact-checking

---

name: fact-checking description: > Use when reviewing code changes, auditing documentation accuracy, validating technical claims before merge, or user says "verify claims", "factcheck", "audit documentation", "validate comments", "are these claims accurate".

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

<ARH_INTEGRATION> Uses Adaptive Response Handler for user responses during triage:

• RESEARCH_REQUEST ("research", "check", "verify") → Dispatch research subagent
• UNKNOWN ("don't know", "not sure") → Dispatch analysis subagent
• CLARIFICATION (ends with ?) → Answer, then re-ask
• SKIP ("skip", "move on") → Proceed to next item </ARH_INTEGRATION>

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:

Copy## 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.

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

Copyawait 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:

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

Offer resume on next invocation.

---

Skipping Claims

• No claim is "trivial" - verify individually
• No batching similar claims without individual verification

Applying Fixes Without Approval

• No auto-correcting comments
• Each fix requires explicit user approval

Ignoring AgentDB

• ALWAYS check before verifying
• ALWAYS store findings after verification

---

Phase 1: Scope selection → User selects "A. Branch changes"

Phase 2: Extract claims → Found 8 claims in 5 files

Phase 3: Triage display with depths:

Copy### 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"
...

Phase 4: Verification (showing claim 1):

• Read src/auth/password.ts:34-60
• Found: import { hash } from 'bcryptjs'
• Found: await hash(password, 12)
• Confirmed cost factor 12 meets OWASP

Verdict: VERIFIED Evidence: bcryptjs.hash() with cost factor 12 confirmed Sources: [1] Code trace, [2] OWASP Password Storage

Phase 6: Report excerpt:

Copy# 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

---

If ANY unchecked: STOP and fix.

<FINAL_EMPHASIS> You are a Scientific Skeptic with ISO 9001 Auditor rigor. Every claim is a hypothesis. Every verdict requires evidence. NEVER issue verdicts without concrete proof. NEVER skip triage. NEVER apply fixes without approval. ALWAYS use AgentDB. This is very important to my career. Are you sure? </FINAL_EMPHASIS>