majiayu000 Invariant Principles
- Claims are hypotheses - Every claim requires empirical evidence before verdict
- Evidence before verdict - No verdict without traceable, citable proof
- User controls scope - User selects scope and approves all fixes
- Deduplicate findings - Check AgentDB before verifying to avoid redundant work
- Learn from trajectories - Store verification trajectories in ReasoningBank for improvement
Inputs
| Input | Required | Description |
|---|---|---|
scope |
Yes | Target for fact-checking: branch changes, uncommitted files, or full repo |
modes |
No | Enabled modes: Missing Facts, Extraneous Info, Clarity Mode (default: all) |
autonomous |
No | If true, skip interactive prompts and use defaults |
Outputs
| Output | Type | Description |
|---|---|---|
verification_report |
Inline | Summary, findings by category, bibliography |
implementation_plan |
Inline | Proposed fixes for refuted/stale claims |
glossary |
Inline | Key facts extracted (Clarity Mode only) |
state_checkpoint |
File | .fact-checking/state.json for interruption recovery |
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
Ask scope BEFORE extraction. No exceptions.
| Option | Method |
|---|---|
| Branch changes | git diff $(git merge-base HEAD main)...HEAD --name-only |
| Uncommitted | git diff --name-only + git diff --cached --name-only |
| Full repo | All code/doc patterns |
Phase 2: Claim Extraction
Sources: Comments (//, #, /* */), docstrings, markdown, commits, PR descriptions, naming (validateX, safeX, ensureX)
Categories:
| Category | Examples | Agent |
|---|---|---|
| Technical | "O(n log n)", "matches RFC" | CorrectnessAgent |
| Security | "sanitized", "XSS-safe", "bcrypt" | SecurityAgent |
| Concurrency | "thread-safe", "atomic", "lock-free" | ConcurrencyAgent |
| Performance | "O(n)", "cached 5m", "lazy-loaded" | PerformanceAgent |
| Configuration | "defaults to 30s", "env var X" | ConfigurationAgent |
| Historical | "workaround for bug", "fixes #123" | HistoricalAgent |
| Documentation | URLs, examples, test coverage claims | DocumentationAgent |
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:
- 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
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
});
// 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
Every verdict MUST have concrete evidence. NO exceptions.
| Verdict | Evidence Required |
|---|---|
| Verified | test output, code trace, docs, benchmark |
| Refuted | failing test, contradicting code |
| Incomplete | base verified + missing elements |
| Inconclusive | document attempts and why insufficient |
| Stale | when true, what changed, current state |
| Extraneous | value analysis shows no added info |
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
NEVER apply fixes without explicit per-fix user approval.
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.