Step 1: What phase am I in? (scope selection, extraction, triage, verification, reporting) Step 2: For verification - what EXACTLY is being claimed? Step 3: What evidence would PROVE this claim true? Step 4: What evidence would PROVE this claim false? Step 5: Have I checked AgentDB for existing findings on similar claims? Step 6: What is the appropriate verification depth?

Now proceed with confidence following this checklist to achieve outstanding results.

Factchecker Workflow

Phase 1: Scope Selection

ALWAYS ask user to select scope before extracting any claims.

Use AskUserQuestion with these options:

After selection, identify the target files using:

• Branch: git diff $(git merge-base HEAD main)...HEAD --name-only + git diff --name-only
• Uncommitted: git diff --name-only + git diff --cached --name-only
• Full repo: All files matching code/doc patterns

Phase 2: Claim Extraction

Extract claims from all scoped files. See references/claim-patterns.md for extraction patterns.

Claim Sources

Claim Categories

Also Flag

• Ambiguous: Wording unclear, multiple interpretations possible
• Misleading: Technically true but implies something false
• Jargon-heavy: Too technical for intended audience

Phase 3: Triage with ARH

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

Display claims grouped by category with recommended depths:

## 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"
3. [SHALLOW] src/api.ts:12 - "rate limited to 100 req/min"
4. [MEDIUM] src/session.ts:56 - "session tokens cryptographically random"

### Performance (3 claims)
5. [DEEP] src/search.ts:23 - "O(log n) lookup"
...

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

Depth Definitions

Triage Question Processing (ARH Pattern)

For each triage-related question:

1. Present question with claims and depth recommendations

2. Process response using ARH pattern:

   • DIRECT_ANSWER: Accept depth adjustments, continue to verification
   • RESEARCH_REQUEST: Dispatch subagent to analyze claim context, regenerate depth recommendations
   • UNKNOWN: Dispatch analysis subagent, provide evidence quality assessment, re-ask
   • CLARIFICATION: Explain depth levels with examples from current claims
   • SKIP: Use recommended depths, proceed to verification

3. After research dispatch:

   • Run claim complexity analysis
   • Regenerate depth recommendations with evidence
   • Present updated recommendations

Example:

Question: "Claim 2 marked DEEP: 'SQL injection safe'. Verify depth?"
User: "I don't know, can you check how complex the verification would be?"

ARH Processing:
→ Detect: UNKNOWN type
→ Action: Analyze claim verification complexity
  "Analyze src/db.ts:89 for parameterization patterns and edge cases"
→ Return: "Found 3 query sites, all use parameterized queries, no string interpolation"
→ Regenerate: "Analysis shows straightforward parameterization verification. MEDIUM depth sufficient (code trace). Proceed?"

Phase 4: Parallel Verification

Spawn category-based agents via swarm-orchestration for parallel verification.

Agent Architecture

Use swarm-orchestration with hierarchical topology:

await swarm.init({
  topology: 'hierarchical',
  queen: 'factchecker-orchestrator',
  workers: [
    'SecurityAgent',
    'CorrectnessAgent',
    'PerformanceAgent',
    'ConcurrencyAgent',
    'DocumentationAgent',
    'HistoricalAgent',
    'ConfigurationAgent'
  ]
});

Shared Context via AgentDB

Before verifying ANY claim, check AgentDB for existing findings.

// Check for existing verification
const existing = await agentdb.retrieveWithReasoning(claimEmbedding, {
  domain: 'factchecker-findings',
  k: 3,
  threshold: 0.92
});

if (existing.memories.length > 0 && existing.memories[0].similarity > 0.92) {
  // Reuse existing verdict
  return existing.memories[0].pattern;
}

// After verification, store finding
await agentdb.insertPattern({
  type: 'verification-finding',
  domain: 'factchecker-findings',
  pattern_data: JSON.stringify({
    embedding: claimEmbedding,
    pattern: {
      claim: claimText,
      location: fileAndLine,
      verdict: verdict,
      evidence: evidenceList,
      bibliography: sources,
      depth: depthUsed,
      timestamp: Date.now()
    }
  }),
  confidence: evidenceConfidence,
  usage_count: 1,
  success_count: verdict === 'verified' ? 1 : 0
});

Per-Agent Responsibilities

See references/verification-strategies.md for detailed per-agent strategies.

Phase 5: Verdicts

Every verdict MUST have concrete evidence. NO exceptions.

Phase 6: Report Generation

Generate markdown report using references/report-template.md.

Report Sections

1. Header: Timestamp, scope, claim counts by verdict
2. Summary: Table of verdicts with action requirements
3. Findings by Category: Each claim with verdict, evidence, sources
4. Bibliography: All sources cited with consistent numbering
5. Implementation Plan: Prioritized fixes for non-verified claims

Bibliography Entry Formats

Phase 7: Learning via ReasoningBank

After report generation, store verification trajectories:

await reasoningBank.insertPattern({
  type: 'verification-trajectory',
  domain: 'factchecker-learning',
  pattern_data: JSON.stringify({
    embedding: await computeEmbedding(claim.text),
    pattern: {
      claimText: claim.text,
      claimType: claim.category,
      location: claim.location,
      depthUsed: depth,
      stepsPerformed: verificationSteps,
      verdict: verdict,
      timeSpent: elapsedMs,
      evidenceQuality: confidenceScore
    }
  }),
  confidence: confidenceScore,
  usage_count: 1,
  success_count: 1
});

Learning Applications

• Depth prediction: Learn which claims need deep verification
• Strategy selection: Learn which verification approaches work best
• Ordering optimization: Prioritize claims with high refutation likelihood
• False positive reduction: Skip shallow verification for reliably-accurate patterns

Phase 8: Fix Application

After user reviews report:

1. Present implementation plan for non-verified claims
2. For each fix, show proposed change and ask for approval
3. Apply approved fixes
4. Re-verify affected claims if requested

NEVER apply fixes without explicit per-fix user approval.

Interruption Handling

If verification is interrupted:

1. Checkpoint: Save state to .factchecker/state.json after each claim
2. Partial report: Generate report from completed verifications
3. Resume: On next invocation, offer to resume from checkpoint

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

I'll help you verify claims in your code. First, let me confirm the scope:

What should I factcheck?
A. Branch changes (diff from merge-base with main) [Recommended]
B. Uncommitted changes only (staged + unstaged)
C. Full repository

Analyzing branch feature/auth-refactor (12 commits since main)...

Found 8 claims in 5 files.

## Claims Found: 8

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

### Correctness (3 claims)
3. [SHALLOW] src/utils/validate.ts:12 - "validates email format per RFC 5322"
4. [MEDIUM] src/api/handler.ts:45 - "returns 404 when user not found"
5. [SHALLOW] src/cache/store.ts:23 - "TTL defaults to 300 seconds"

### Performance (1 claim)
6. [DEEP] src/search/index.ts:89 - "O(log n) binary search"

### Historical (2 claims)
7. [SHALLOW] src/utils/legacy.ts:15 - "TODO: remove after issue #142 resolved"
8. [MEDIUM] src/compat/shim.ts:34 - "workaround for Safari WebKit bug #12345"

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

# Factchecker Report

**Generated:** 2025-12-21T15:30:00Z
**Scope:** Branch feature/auth-refactor (12 commits since main)
**Claims Found:** 8
**Verified:** 5 | **Refuted:** 1 | **Stale:** 1 | **Inconclusive:** 1

## Summary
| Verdict | Count | Action |
|---------|-------|--------|
| Verified | 5 | None |
| Refuted | 1 | Fix required |
| Stale | 1 | Remove/update |
| Inconclusive | 1 | Manual review |

## Findings

### Security

#### Verified: "passwords hashed with bcrypt"
- **Location:** src/auth/password.ts:34
- **Evidence:** bcryptjs.hash() with cost factor 12 confirmed
- **Sources:** [1], [2]

...

## Bibliography
[1] Code trace: src/auth/password.ts:34-60 - bcryptjs import and hash() call
[2] OWASP Password Storage - https://cheatsheetseries.owasp.org/... - "Use bcrypt with cost 10+"
...

## Implementation Plan
### High Priority
1. [ ] src/cache/store.ts:23 - TTL is 60s not 300s, update comment or code
### Medium Priority
2. [ ] src/utils/legacy.ts:15 - Issue #142 closed 2024-01, remove workaround