lhl/realitycheck/check

Full Analysis Workflow

Full Reality Check analysis - fetch source, perform 3-stage analysis, extract claims, register to database, and validate. The flagship command for rigorous source analysis.

Usage

/skill:check <url> [--domain DOMAIN] [--quick] [--no-register] [--continue]

The flagship Reality Check command for rigorous source analysis.

Prerequisites

Environment

Set REALITYCHECK_DATA to point to your data repository:

export REALITYCHECK_DATA=/path/to/realitycheck-data/data/realitycheck.lance

The PROJECT_ROOT is derived from this path - all analysis files go there.

CLI Commands

Reality Check provides CLI tools (rc-db, rc-validate, rc-export, rc-embed).

Check availability:

which rc-db  # Should show path if pip-installed

If commands are not found, either:

1. Install: pip install realitycheck (recommended)
2. Use uv run from framework directory: uv run python scripts/db.py ...
3. Add framework as submodule and use: .framework/scripts/db.py ...

Red Flags: Wrong Repository

IMPORTANT: Always write to the DATA repository, never to the framework repository.

If you see these directories, you're in the framework repo (wrong place for data):

• scripts/
• tests/
• integrations/
• methodology/

Stop and verify REALITYCHECK_DATA is set correctly.

Data Source of Truth

LanceDB is the source of truth, not YAML files.

• Query sources: rc-db source get <id> or rc-db source list
• Query claims: rc-db claim get <id> or rc-db claim list
• Search: rc-db search "query"

Ignore YAML files like claims/registry.yaml or reference/sources.yaml - these are exports/legacy format.

Workflow Steps

1. Start Tracking - Begin token usage capture (lifecycle mode)
2. Fetch - Retrieve and parse source content

• Primary: WebFetch for most URLs
• Alternative: curl -L -sS "URL" | rc-html-extract - --format json
• rc-html-extract returns structured {title, published, text, headings, word_count}
• Use the extract tool when you need clean metadata or main text extraction

1. Metadata - Extract title, author, date, type, generate source-id
2. Stage 1: Descriptive - Neutral summary, key claims, argument structure
3. Stage 2: Evaluative - Evidence quality, fact-checking, disconfirming evidence

• DB-first for crux factuals: run rc-db search "<neutral keywords>" before external search
• Web discovery: use your environment's web search capability (e.g., Claude WebSearch, Codex web.run search_query)
• Minimum verification attempt: for each crux [F] claim, run >=2 distinct queries and record attempts
• Status contract: use ok, x, nf, blocked, ? in "Key Factual Claims Verified"
• Review gate: do not mark [REVIEWED] if any crux [F] claim remains ?

1. Stage 3: Dialectical - Steelman, counterarguments, synthesis
2. Neutral Analyst Prose Pass - Clean up analyst-authored prose without changing source content, quotes, claim IDs, evidence levels, or credences
3. Extract - Format claims as YAML
4. Register - Add source and claims to database
5. Provenance (for high-credence claims) - Link evidence + capture reasoning trails
6. Complete Tracking - Finalize token usage + register analysis_logs row
7. Validate - Run integrity checks
8. README - Update data project analysis index
9. File Inbox - Move/archive inbox items to permanent locations
10. Commit - Stage and commit changes to data repo
11. Push - Push to remote
12. Report - Generate summary

Multi-source Requests (Compare / Contrast)

If the prompt includes multiple sources (multiple URLs/repos/papers) or explicitly asks for compare/contrast, /skill:check is responsible for the full multi-source workflow end-to-end:

1. Run the source-analysis workflow once per source (one analysis/sources/<source-id>.md per source)
2. Then, in the same run, also write a single cross-source synthesis at analysis/syntheses/<synth-id>.md

The synthesis should link back to the relevant source analyses and resolve (or clearly frame) points of agreement and disagreement.

Use /skill:rc-synthesize as a standalone command when you want to:

• create a synthesis later from existing source analyses
• update/refine an existing synthesis without re-running checks

Analysis Output Contract

Every analysis must produce a human-auditable analysis file at: PROJECT_ROOT/analysis/sources/<source-id>.md

The analysis must include:

1. Metadata (Source ID, URL, author, date/type)
2. Legends (top-of-file quick reference)
3. Three-stage analysis (Stages 1-3)
4. Claim tables with evidence + credence
5. Extracted claims artifact (embedded YAML or separate file)
6. Analysis Log (append-only pass history + tool/model/tokens/cost when available)

If an analysis lacks claim tables (IDs, evidence levels, credence) it is not complete.

Multi-source Output

For multi-source requests, produce:

• One source analysis per source: analysis/sources/<source-id>.md
• One synthesis (required unless the user explicitly asks not to): analysis/syntheses/<synth-id>.md

Required Elements

Stage 1 (Descriptive):

• Source Metadata table
• Core Thesis (1-3 sentences)
• Key Claims table (rigor-v1: Layer/Actor/Scope/Quantifier + Verified? + Falsifiable By)
• Argument Structure diagram
• Theoretical Lineage
• Scope & Limitations

Stage 2 (Evaluative):

• Key Factual Claims Verified (Claim ID + Crux? + Search Notes + status codes)
• Disconfirming Evidence Search
• Corrections & Updates (including capture failures)
• Internal Tensions / Self-Contradictions
• Persuasion Techniques
• Unstated Assumptions
• Evidence Assessment
• Credence Assessment

Stage 3 (Dialectical):

• Steelmanned Argument
• Strongest Counterarguments
• Supporting Theories (with source IDs)
• Contradicting Theories (with source IDs)
• Synthesis Notes
• Claims to Cross-Reference

End:

• Claim Summary table (all claims)
• Claims to Register (YAML)
• Credence in Analysis (0.0-1.0)

Neutral Analyst Prose Pass

Before finalizing an analysis or synthesis, run a short pass over the analyst-authored prose.

Scope:

• Applies to the analyst's prose: summaries, thesis statements, evidence

assessments, credence reasoning, synthesis notes, and recommendations.

• Does not apply to source text, direct quotes, titles, quoted slogans, or

sections that intentionally analyze rhetoric/persuasion techniques.

• Preserve source wording when it is evidence for rhetoric, framing, or

persuasion. Label it as source language instead of adopting it as the analyst's voice.

Rewrite rules:

• State facts, claim IDs, dates, sources, methods, search results, evidence

levels, credences, falsifiers, and open questions directly.

• Remove rhetorical setup, marketing language, reassurance frames, vague

intensifiers, hedge stacks, and conclusion recaps from analyst prose.

• Replace vague quantifiers (many, several, various) with counts, IDs,

bounded scopes, or unknown.

• Do not change claim IDs, evidence levels, credences, source-backed facts, or

quotes unless the analysis records why.

Analysis Template

Use this structure for analysis documents:

# Source Analysis: [Title]
 
> **Claim types**: `[F]` fact, `[T]` theory, `[H]` hypothesis, `[P]` prediction, `[A]` assumption, `[C]` counterfactual, `[S]` speculation, `[X]` contradiction
> **Evidence**: **E1** systematic review/meta-analysis; **E2** peer-reviewed/official stats; **E3** expert consensus/preprint; **E4** credible journalism/industry; **E5** opinion/anecdote; **E6** unsupported/speculative
 
## Metadata
 
| Field | Value |
|-------|-------|
| **Source ID** | [author-year-shorttitle] |
| **Title** | [extracted from source] |
| **Author(s)** | [name(s)] |
| **Date** | [YYYY-MM-DD or YYYY] |
| **Type** | [PAPER/ARTICLE/BLOG/REPORT/INTERVIEW/etc.] |
| **URL** | [source URL] |
| **Reliability** | [0.0-1.0] |
| **Rigor Level** | [SPITBALL/DRAFT/REVIEWED/CANONICAL] |
 
## Stage 1: Descriptive Analysis
 
### Core Thesis
[1-3 sentence summary of main argument]
 
### Key Claims
 
| # | Claim | Claim ID | Layer | Actor | Scope | Quantifier | Type | Domain | Evid | Credence | Verified? | Falsifiable By |
|---|-------|----------|-------|-------|-------|------------|------|--------|------|----------|-----------|----------------|
| 1 | [claim text] | DOMAIN-YYYY-NNN | ASSERTED/LAWFUL/PRACTICED/EFFECT | ICE/CBP/DHS/DOJ/COURT/OTHER | who=...; where=...; when=... | none/some/often/most/always/OTHER:<...> | [F/T/H/P/A/C/S/X] | DOMAIN | E1-E6 | 0.00-1.00 | [source or ?] | [what would refute] |
| 2 | | | | | | | | | | | | |
| 3 | | | | | | | | | | | | |
 
**Column guide**:
-**Claim**: Concise statement of the claim
-**Claim ID**: Format `DOMAIN-YYYY-NNN` (e.g., TECH-2026-001)
-**Layer**: `ASSERTED` (positions/claims made), `LAWFUL` (controlling law), `PRACTICED` (practice), `EFFECT` (causal effects)
-**Actor**: Who is acting (e.g., ICE/CBP/DHS/DOJ/COURT). Use `OTHER:<text>` or `N/A` only when not applicable.
-**Scope**: Mini-schema string (e.g., `who=...; where=...; when=...; process=...; predicate=...; conditions=...`)
-**Quantifier**: `none|some|often|most|always|OTHER:<text>|N/A`
-**Type**: `[F]` fact, `[T]` theory, `[H]` hypothesis, `[P]` prediction, `[A]` assumption, `[C]` counterfactual, `[S]` speculation, `[X]` contradiction
-**Domain**: Primary domain code (TECH/LABOR/ECON/GOV/SOC/RESOURCE/TRANS/GEO/INST/RISK/META)
-**Evid**: Evidence level E1-E6
-**Credence**: Probability estimate 0.00-1.00
-**Verified?**: Source reference if verified, `?` if unverified
-**Falsifiable By**: What evidence would refute this claim
 
### Argument Structure
 
[Is this a chain argument? What's the logical flow?]
 

[Claim A]

v [Claim B]

v [Claim C]

v [Conclusion]

 
**Chain Analysis** (if applicable):
- **Weakest Link**: [Which step?]
- **Why Weak**: [Explanation]
- **If Link Breaks**: [What happens to conclusion?]
- **Alternative Paths**: [Can conclusion be reached differently?]
 
### Theoretical Lineage
 
[What traditions/thinkers does this build on?]
 
- **Primary influences**: [List key thinkers, schools of thought]
- **Builds on**: [Specific theories or frameworks this extends]
- **Departs from**: [Where this diverges from its intellectual predecessors]
- **Novel contributions**: [What's genuinely new here]
 
### Scope & Limitations
[What does this source attempt to explain? What does it explicitly not address?]
 
## Stage 2: Evaluative Analysis
 
### Internal Coherence
[Does the argument follow logically? Any contradictions?]
 
### Key Factual Claims Verified
 
> **Requirement**: Must include >=1 **crux claim** (central to thesis), not just peripheral numerics.
 
| Claim ID | Claim (paraphrased) | Crux? | Source Says | Actual | External Source | Search Notes | Status |
|----------|---------------------|-------|-------------|--------|-----------------|-------------|--------|
| [e.g., TECH-2026-001] | [e.g., "China makes 50% of X"] | N | [assertion] | [verified value] | [URL/ref] | [q1; q2; date] | ok / x / nf / blocked / ? |
| [e.g., TECH-2026-002] | [e.g., "Elite consensus on Y"] | **Y** | [assertion] | [verified or ?] | [URL/ref or blank] | [queries tried + blockers] | ok / x / nf / blocked / ? |