| name | lumen-fact-check |
| description | Verify factual accuracy of a document against the actual codebase, then propose or apply in-place corrections. Invoke when user asks to fact-check, verify this doc, is this still accurate, audit this doc, or supplies a doc that may have drifted from code. |
| version | 0.1.9 |
lumen-fact-check
Read a document → extract every verifiable claim → check each against code + git → correct in place → append a verification summary.
📄 Rendered example: docs/examples/fact-check/ (before/after pair, 11 cited corrections)
Tier: capability (atomic) — does not invoke other lumen skills. Composites and playbooks may invoke it.
When to invoke
Triggers: fact-check, verify this doc, is this still accurate, check this against the codebase, does this README match the code, audit this doc.
Pipeline
Follow the full recipe in references/fact-check-recipe.md (lifted from visual-explainer). Summary:
- Resolve target file from
$1 (explicit path) or default to most recently modified ~/.agent/lumen/*.html or ~/.agent/diagrams/*.html.
- Auto-detect document type (HTML review page vs plan/spec markdown vs other) and adjust verification strategy.
- Phase 1 — Extract claims:
- Quantitative (line counts, file counts, metrics)
- Naming (functions, types, modules, file paths)
- Behavioral (what code does, before/after comparisons)
- Structural (architecture, dependencies, module boundaries)
- Temporal (git history claims, timeline entries)
- Skip subjective analysis (opinions, design judgments).
- Phase 2 — Verify against source:
- Re-read every referenced file; check signatures + behavior.
- For git history claims: re-run
git diff --stat, git log, git diff --name-status; compare numbers.
- For diff-reviews: read both
git show <ref>:file and working tree to catch before/after swaps.
- Classify each claim by outcome: Confirmed / Corrected / Unverifiable.
- Assign a confidence level to every checked claim: High (primary-source exact match), Medium (verified but required interpretation or inference), Low (secondary, outdated, or pushes beyond explicit source statement), Unverifiable (cannot be checked with available tools).
- Phase 3 — Correct in place via surgical
Edit calls.
- Preserve layout, CSS, structure.
- For HTML: keep Mermaid diagrams unless a label is factually wrong.
- For markdown: keep heading structure + organization.
- Phase 4 — Append verification summary:
- HTML: insert as styled banner at top or final section, matching page styling.
- Markdown: append
## Verification Summary at end.
- Include: claims checked, confirmed count, corrections (with
file.ts:LN source for each fix), unverifiable flags.
- Phase 5 — Report. Tell the user what was checked, corrected, opened. If nothing needed correction, say so.
Boundaries (lift verbatim from upstream)
This is not a re-review. It does not second-guess analysis, opinions, or design judgments. It does not change the document's structure or organization. It is a fact-checker — it verifies that the data presented matches reality, corrects what doesn't, and leaves everything else alone.
Output
The corrected document, in place. Plus a verification summary section. The user sees both.
Quality checks
- Every claim was either verified, corrected, or flagged unverifiable — none silently passed.
- Corrections cite source location (
file.ts:LN or git command).
- Subjective analysis was untouched.
- Document structure preserved.
- Confidence level (High/Medium/Low/Unverifiable) is assigned to every checked claim and surfaced in the verification summary.
- Uncertainty is transparent: Low and Unverifiable claims include an explanation of why evidence is weak and what would upgrade confidence.
- Follow
skills/_shared/instructions.md for evidence rules, citation format, and validation conventions.
PI extension route (v0.1.x)
Permanently skill-path only by design. lumen-fact-check needs Read / Grep / Bash / Edit access to verify claims against the actual codebase and apply surgical corrections. A deterministic PI tool cannot perform this agentic verification loop.
Sources
