Back to Details

backward-traceability

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Backward Traceability

反向可追溯性

Make every number in the final PDF hyperlink back to the exact code line that produced it.
让最终PDF中的每个数字都可以通过超链接跳转至生成它的具体代码行。

Input

输入

  • $0
    — Paper project directory containing code and LaTeX files
  • $0
    — 包含代码和LaTeX文件的论文项目目录

References

参考资料

  • Traceability patterns and LaTeX commands: 
    ~/.claude/skills/backward-traceability/references/traceability-patterns.md
  • 可追溯模式与LaTeX命令：
    ~/.claude/skills/backward-traceability/references/traceability-patterns.md

Scripts

脚本

Scan hypertarget/hyperlink references

扫描hypertarget/hyperlink引用

bash
python ~/.claude/skills/backward-traceability/scripts/ref_numeric_values.py \
  --scan paper/main.tex --output report.json
Reports: all hypertargets, hyperlinks, orphan references, unreferenced numeric values.
bash
python ~/.claude/skills/backward-traceability/scripts/ref_numeric_values.py \
  --scan paper/main.tex --output report.json
报告内容：所有hypertarget、hyperlink、孤立引用、未被引用的数值。

Verify cross-reference integrity

校验交叉引用完整性

bash
python ~/.claude/skills/backward-traceability/scripts/ref_numeric_values.py \
  --verify paper/main.tex --code-output results.txt
Cross-checks values between paper text and code output. Reports mismatches.
bash
python ~/.claude/skills/backward-traceability/scripts/ref_numeric_values.py \
  --verify paper/main.tex --code-output results.txt
交叉校验论文文本与代码输出的数值，报告不匹配项。

Workflow

工作流程

Step 1: Tag Code Outputs

步骤1：标记代码输出

For every numeric value produced by experiment code, add hypertarget tags:
python
undefined
对于实验代码生成的每个数值，添加hypertarget标签：
python
undefined

In experiment code output:

In experiment code output:

print(f"\hypertarget{{R1a}}{{45.3}}") # Mean accuracy print(f"\hypertarget{{R1b}}{{2.1}}") # Std deviation

Label format: `{prefix}{line_number}{letter}` where letter = a, b, c... for multiple values on same line.
print(f"\hypertarget{{R1a}}{{45.3}}") # Mean accuracy print(f"\hypertarget{{R1b}}{{2.1}}") # Std deviation

标签格式：`{前缀}{行号}{字母}`，其中字母a、b、c...用于标识同一行的多个数值。

Step 2: Reference in Paper Text

步骤2：在论文文本中引用

Use 
\hyperlink
to create clickable references in the paper:
latex
Our method achieves \hyperlink{R1a}{45.3}\% accuracy
($\pm$\hyperlink{R1b}{2.1}).
使用
\hyperlink
在论文中创建可点击的引用：
latex
Our method achieves \hyperlink{R1a}{45.3}\% accuracy
($\pm$\hyperlink{R1b}{2.1}).

Step 3: Use \num for Computed Values

步骤3：对计算值使用\num

For values derived from other values, use 
\num{}
for compile-time evaluation:
latex
% \num{formula, "explanation"} → evaluated at compile time
The improvement is \num{45.3 - 38.7, "accuracy gain"}\%.
对于从其他值衍生而来的数值，使用
\num{}
实现编译时计算：
latex
% \num{formula, "explanation"} → evaluated at compile time
The improvement is \num{45.3 - 38.7, "accuracy gain"}\%.

Step 4: Generate Appendix Code Listing

步骤4：生成附录代码清单

Create an appendix with the full code listing, with 
\hypertarget
anchors at relevant lines:
latex
\section*{Appendix: Code Listing}
\begin{lstlisting}[escapechar=@]
@\hypertarget{code1}{}@result = model.evaluate(test_data)
@\hypertarget{code2}{}@accuracy = result['accuracy']
\end{lstlisting}
创建包含完整代码清单的附录，在相关代码行处添加
\hypertarget
锚点：
latex
\section*{Appendix: Code Listing}
\begin{lstlisting}[escapechar=@]
@\hypertarget{code1}{}@result = model.evaluate(test_data)
@\hypertarget{code2}{}@accuracy = result['accuracy']
\end{lstlisting}

Step 5: Verify Traceability

步骤5：校验可追溯性

  • Every number in the paper text must have a corresponding 
    \hypertarget
    in the code
  • Every 
    \num{}
    formula must evaluate correctly
  • Click-test: every hyperlink in the PDF must jump to the correct code line
  • 论文文本中的每个数字都必须在代码中有对应的
    \hypertarget
  • 每个
    \num{}
    公式都必须能正确计算
  • 点击测试：PDF中的每个超链接都必须跳转至正确的代码行

LaTeX Setup

LaTeX配置

Required packages:
latex
\usepackage{hyperref}
\usepackage{listings}
所需依赖包：
latex
\usepackage{hyperref}
\usepackage{listings}

Rules

规则

  • Every numeric result in the paper MUST trace to code output
  • Never manually type numbers — always reference tagged outputs
  • Use 
    \num{}
    for any derived/computed values
  • Code listing in appendix must match actual executed code
  • Verify all hyperlinks resolve correctly after compilation
  • 论文中的每个数值结果都必须可追溯至代码输出
  • 绝对不要手动输入数字——始终引用已标记的输出
  • 对所有衍生/计算值使用
    \num{}
  • 附录中的代码清单必须与实际执行的代码一致
  • 编译后校验所有超链接可正常跳转

Related Skills

相关技能

  • Upstream: experiment-code, data-analysis
  • Downstream: paper-compilation
  • See also: paper-assembly
  • 上游：experiment-code、data-analysis
  • 下游：paper-compilation
  • 另见：paper-assembly