mcpField
B
backward-traceability

backward-traceability

github.com/lingzhi227Documents4402.2k installsUpdated 35w ago
Repository

About backward-traceability

backward-traceability is a skill for linking numbers in a research paper’s final PDF to the code lines that produced them. It defines a workflow for tagging outputs, adding LaTeX links, and checking numeric references.

Key features

  1. 01Tag numeric code outputs
  2. 02Link paper values to code
  3. 03Evaluate derived values with \num
  4. 04Generate an appendix code listing
  5. 05Check traceability and mismatches

Use cases

  1. 01Tracing reported results to experiment code
  2. 02Adding clickable links to paper values
  3. 03Auditing numeric references before publication

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/lingzhi227/agent-research-skills --skill backward-traceability

After installing, type/backward-traceabilityin Claude Code to confirm it loaded.

Bundled filesreferences/traceability-patterns.mdscripts/ref_numeric_values.py

Details

From the project README

Backward Traceability

Make every number in the final PDF hyperlink back to the exact code line that produced it.

Input

  • $0 — Paper project directory containing code and LaTeX files

References

  • Traceability patterns and LaTeX commands: ~/.claude/skills/backward-traceability/references/traceability-patterns.md

Scripts

Scan hypertarget/hyperlink references
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.

Verify cross-reference integrity
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.

Workflow

Step 1: Tag Code Outputs

For every numeric value produced by experiment code, add hypertarget tags:

# 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.

Step 2: Reference in Paper Text

Use \hyperlink to create clickable references in the paper:

Our method achieves \hyperlink{R1a}{45.3}\% accuracy
($\pm$\hyperlink{R1b}{2.1}).
Step 3: Use \num for Computed Values

For values derived from other values, use \num{} for compile-time evaluation:

% \num{formula, "explanation"} → evaluated at compile time
The improvement is \num{45.3 - 38.7, "accuracy gain"}\%.
Step 4: Generate Appendix Code Listing

Create an appendix with the full code listing, with \hypertarget anchors at relevant lines:

\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
  • 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

LaTeX Setup

Required packages:

\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

Related Skills

Comments

Markdown supported