| name | knowledge-hygiene-verify-claims |
| description | Run multi-source-research + rationalization-trap-check on each load-bearing claim in target doc, spec, or PR. Surfaces conflicts + rationalization-traps before commit/merge. 對目標跑多源+陷阱檢核。 Use when: pre-merge fact-check on doc/PR, post-spec audit before locking architectural decision, validating claim contradicting Phase 0 high-confidence bullet, periodic audit of /docs/research/ outputs. |
| disable-model-invocation | true |
| argument-hint | "[target — file path, directory, or PR ref like #123 or owner/repo#123]" |
Verify-Claims Command
對目標文檔或 PR 之每 load-bearing claim 跑 knowledge-hygiene 全管道：採集 ≥2 源 → 衝突檢核 → 理性化陷阱檢核 → 結構化報告。本命令為 multi-source-research skill 與 rationalization-trap-check skill 之 orchestrator，不自身做 source 採集或 conflict 判定——彼皆委下游。
Usage
/knowledge-hygiene:verify-claims docs/research/K2-knowledge-hygiene-from-papers.md
/knowledge-hygiene:verify-claims docs/superpowers/specs/2026-04-26-knowledge-hygiene-design.md
/knowledge-hygiene:verify-claims plugins/knowledge-hygiene/
/knowledge-hygiene:verify-claims #123
/knowledge-hygiene:verify-claims standardbeagle/standardbeagle-tools#123
Provenance
- K2 design doc:
docs/research/K2-knowledge-hygiene-from-papers.md §3.1 (provenance per claim) + §3.3 (rationalization-trap)
- Pipeline composition: this command is a thin orchestrator over the two skills + one agent in this plugin. No new logic lives here.
Process
Step 1 — Identify Target
If $ARGUMENTS is provided, use it. Otherwise ask the user for the target.
Resolve the target shape:
- File path → read the file with
Read.
- Directory path → glob for
*.md, *.txt, *.rst candidates with Glob; iterate per file.
- PR ref (
#NNN or owner/repo#NNN) → use gh pr view <ref> --json title,body,files to fetch the PR body + changed files; treat each as a target file.
Step 2 — Extract Load-Bearing Claims
For each target document, identify load-bearing claims — assertions that, if false, would change a downstream decision. Heuristics:
- Numeric / boolean assertions about runtime behavior (TTLs, version numbers, feature flags).
- Causal claims ("X causes Y", "without X, Y fails").
- Authority claims ("the spec says", "the docs require", "per RFC NNNN").
- Architectural decisions and the rationale section of design docs.
- Security / data-integrity assertions.
Skip:
- Stylistic / aesthetic statements.
- Hedged exploratory prose ("we might consider", "one option is").
- Comments / examples that are illustrative only.
When in doubt, prefer to include the claim — false-positives are cheap (an extra conflict-detector call), false-negatives let an ungrounded assertion ship.
Step 3 — Run multi-source-research per claim
For each extracted claim:
- Invoke the
multi-source-research skill (this plugin, skills/multi-source-research/SKILL.md) with the claim as the topic.
- The skill runs gather → conflict-detect → synthesize-with-provenance per its own pipeline.
- Capture the output JSON.
Step 4 — Run rationalization-trap-check on the surrounding reasoning
If the target document includes a reasoning trace, plan, or rationale section adjacent to the claim (e.g., a "Why" section in a PR body, a "Decision" section in a design doc, a CoT block in a spec):
- Invoke the
rationalization-trap-check skill (this plugin) with:
cot_text = the reasoning section.change_text = the claim itself.prior_claims = any prior high-confidence claims this claim might override (gathered from project memory .dartai/memory/, CLAUDE.md, or git history if relevant).
- Capture the verdict.
If no reasoning trace is adjacent (claim stands alone), skip Step 4 for that claim and record rationalization_check: skipped:no-reasoning-trace.
Step 5 — Report
Emit a structured report — one section per claim — for the user:
## Verify-Claims Report — <target>
**Claims audited:** N
**Conflicts surfaced:** M (of which K escalate-to-user)
**Rationalization flags:** P (of which Q flag-strong)
### Claim 1: "<claim text>"
- **Sources gathered:** <count> (<list of source ids>)
- **Conflict check:** <conflict_type> — <recommended_resolution>
- **Reasoning:** <conflict-detector reasoning verbatim>
- **Rationalization check:** <verdict> (<positive signal count>/3 signals)
- **Recommendation:** <one-sentence next action>
### Claim 2: ...
Sort the report so escalate-to-user and flag-strong claims appear first.
Related (optional rendering): 報告默為 inline markdown。若 user 欲瀏覽器可視化（多 claim、需篩排 severity）→ 將 §Step 5 之各 claim section 作 sections 傳 present:html-report，per-claim severity/rationalization 作 badge。純 CI gate 場景無需渲染。
Step 6 — Exit Behavior
The command does NOT modify the target file or block the PR. It surfaces. The user (or a downstream automation invoking this command) decides what to do with the report.
When invoked from a CI pipeline (e.g., a pre-merge GitHub Action), the caller may parse the report's summary line (Conflicts surfaced: M ... Rationalization flags: P) and gate the merge on M == 0 && P == 0. That gating policy lives in the caller, not in this command.
Output
A single markdown report (Step 5 shape). No file writes by default. If the user requests --save-report <path>, write the report to <path>.
Composition Diagram
/knowledge-hygiene:verify-claims <target>
│
├── (Step 2) extract load-bearing claims
│
├── (Step 3, per claim)
│ ▼
│ skills/multi-source-research/SKILL.md
│ │
│ ├── Step 1: gather ≥2 sources
│ ├── Step 2: invoke agents/conflict-detector.md
│ └── Step 3: synthesize-with-provenance
│
├── (Step 4, per claim, when reasoning adjacent)
│ ▼
│ skills/rationalization-trap-check/SKILL.md
│
└── (Step 5) emit structured report
Anti-Patterns
- Auto-blocking merges from this command — the command surfaces; gating is the caller's policy. Hard-blocking would prevent legitimate overrides documented per the ideation / present mini-IDE audit-trail rule.
- Running on every doc indiscriminately —
verify-claims is for load-bearing artifacts (specs, research docs, PR descriptions). Running it on README updates is overkill and trains reviewers to ignore the report.
- Modifying the target file — this command is read-only on the target. If the report recommends a change, the user (or a subsequent edit) makes it.
Forward References
- Citation-verifier agent (
qvd3VBUROdw2, deferred Tier-3) — will add a Step 3.5 between conflict-detect and synthesize: retroactively verify each provenance tag still resolves (file:line exists, web:url loads, git:sha in history). Until it lands, verify-claims trusts the provenance tags as emitted.
