Back to Details

claim-evidence-matrix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claim–Evidence Matrix

主张-证据矩阵（Claim–Evidence Matrix）

Make the survey’s claims explicit and auditable before writing prose.
This should stay bullets-only (NO PROSE). The goal is to make later writing easy and to prevent “template prose” from sneaking in.
在撰写正式文稿（prose）之前，先明确调查的主张并确保其可核查。
内容需仅使用项目符号（禁止正式文稿）。目标是让后续写作更轻松，避免“模板化文稿”混入。

Inputs

输入文件

  • outline/outline.yml
  • papers/paper_notes.jsonl
  • Optional: 
    outline/mapping.tsv
  • outline/outline.yml
  • papers/paper_notes.jsonl
  • 可选：
    outline/mapping.tsv

Output

输出文件

  • outline/claim_evidence_matrix.md
  • outline/claim_evidence_matrix.md

Workflow (heuristic)

工作流程（启发式）

Uses: 
outline/outline.yml
, 
outline/mapping.tsv
.
  1. For each subsection, write 1–3 claims that are:
    • specific (mechanism / assumption / empirical finding)
    • falsifiable (“X reduces tool errors under Y evaluation”, not “X is important”)
  2. For each claim, list ≥2 evidence sources:
    • prefer different styles of evidence (method paper + eval/benchmark paper, or two competing approaches)
  3. Keep it tight: claim → evidence → (optional) caveat/limitations.
  4. If evidence is weak or only abstract-level, say so explicitly (don’t overclaim).
  5. If 
    bibkey
    exists in 
    papers/paper_notes.jsonl
    , include 
    [@BibKey]
    next to evidence items to make later prose/LaTeX conversion smoother.
使用文件：
outline/outline.yml
、
outline/mapping.tsv
  1. 针对每个小节，撰写1-3个符合以下要求的claim：
    • 具体明确（涉及机制/假设/实证发现）
    • 可证伪（例如“在Y评估标准下X可减少工具错误”，而非“X很重要”）
  2. 每个claim需列出至少2个证据来源：
    • 优先选择不同类型的证据（如方法论文 + 评估/基准论文，或两种竞争方案）
  3. 结构简洁：claim → 证据 →（可选）注意事项/局限性
  4. 若证据力度较弱或仅为摘要层面，需明确说明（避免过度主张）
  5. 若
    papers/paper_notes.jsonl
    中存在
    bibkey
    ，请在证据项旁标注
    [@BibKey]
    ，以便后续更顺畅地转换为正式文稿/LaTeX格式

Quality checklist

质量检查清单

  • Every subsection has ≥1 claim.
  • Each claim lists ≥2 evidence sources (or an explicit exception).
  • Claims are not copy-pasted templates (avoid “围绕…总结…” boilerplate).
  • 每个小节至少包含1个claim
  • 每个claim列出至少2个证据来源（或明确说明例外）
  • claim并非复制粘贴的模板（避免“围绕…总结…”这类套话）

Helper script (optional)

辅助脚本（可选）

Quick Start

快速开始

  • python .codex/skills/claim-evidence-matrix/scripts/run.py --help
  • python .codex/skills/claim-evidence-matrix/scripts/run.py --workspace <workspace_dir>
  • python .codex/skills/claim-evidence-matrix/scripts/run.py --help
  • python .codex/skills/claim-evidence-matrix/scripts/run.py --workspace <workspace_dir>

All Options

所有选项

  • See 
    --help
    (this helper is intentionally minimal)
  • 查看
    --help
    （本辅助脚本设计得尽量简洁）

Examples

示例

  • Generate a first-pass matrix, then refine manually:
    • Run the helper once, then refine 
      outline/claim_evidence_matrix.md
      by tightening claims and adding caveats when evidence is abstract-level.
  • 先生成初稿矩阵，再手动优化：
    • 运行一次辅助脚本，然后通过细化claim、为摘要层面的证据添加注意事项来优化
      outline/claim_evidence_matrix.md

Notes

注意事项

  • The helper generates a baseline matrix (claims + evidence) and never overwrites non-placeholder work; in 
    pipeline.py --strict
    it will be blocked only if placeholder markers remain.
  • 辅助脚本会生成基础矩阵（claim + 证据），且绝不会覆盖非占位符内容；在
    pipeline.py --strict
    模式下，仅当存在占位符标记时才会被阻止

Troubleshooting

问题排查

Issue: claims are generic or read like outline boilerplate

问题：claim过于通用或类似大纲套话

Fix:
  • Tighten each claim to a falsifiable statement and add an explicit caveat if evidence is abstract-only.
解决方法：
  • 将每个claim细化为可证伪的表述，若证据仅为摘要层面，需添加明确的注意事项

Issue: you cannot add 
[@BibKey]
because keys are missing

问题：因缺少键值无法添加
[@BibKey]

Fix:
  • Run 
    citation-verifier
    to generate 
    citations/ref.bib
    , then use the produced keys in the matrix.
解决方法：
  • 运行
    citation-verifier
    生成
    citations/ref.bib
    ，然后在矩阵中使用生成的键值