enrich-claims

Enrich Claims: $ARGUMENTS

Improve an existing claims.yaml with real data from the paper. This skill assumes a paper-local concepts.yaml exists or that you will keep concept names consistent until register-concepts runs.

Step 0: Validate

paper_dir="$ARGUMENTS"
ls "$paper_dir"/notes.md 2>/dev/null || echo "MISSING: notes.md"
ls "$paper_dir"/claims.yaml 2>/dev/null || echo "MISSING: claims.yaml"

Both must exist. If claims.yaml is missing, generate it first:

uv run scripts/generate_claims.py "$paper_dir"

This command uses a scripts/... path relative to this skill's directory. It extracts parameters from tables, equations from $$...$$ blocks, and observations from the Testable Properties section. The output has placeholder page numbers (0) and raw concept names — that is what this skill fixes.

Step 1: Read Source Material

Read these files:

• <paper_dir>/claims.yaml — the mechanical extraction to enrich
• <paper_dir>/notes.md — the full paper notes with equations, parameters, context

If available, also read:

• <paper_dir>/paper.pdf or page images in <paper_dir>/pngs/ — for verifying page numbers
• <paper_dir>/concepts.yaml — for aligning concept references with the paper's source-local inventory

Step 2: Enrich Each Claim

Walk through every claim in the file. For each one, improve these fields:

Page Numbers (provenance.page)

Replace page: 0 with the actual page number. Cross-reference:

• The parameter name against sections in notes.md
• Table/figure references
• Section headings in notes.md "Figures of Interest" or equation locations

If the exact page cannot be determined, add provenance.section with the section name and leave page as 0.

Concept Resolution (concept)

The generator produces lowercase underscore names like fundamental_frequency. Check against the paper-local concept inventory:

ls "$paper_dir"/concepts.yaml 2>/dev/null

For each concept name:

• If a matching local_name exists in concepts.yaml, use that exact name
• If a matching proposed_name exists, convert the claim to the corresponding local_name
• If no match exists, keep the descriptive name and flag it for register-concepts to absorb later

SymPy Expressions (sympy)

For equation claims, the generator copies LaTeX into both expression and sympy. Replace sympy with a valid SymPy-parseable expression:

• LaTeX \frac{a}{b} → SymPy a/b
• LaTeX e^{x} → SymPy exp(x)
• LaTeX \sqrt{x} → SymPy sqrt(x)
• LaTeX \sum_{i=0}^{N} → SymPy Sum(f(i), (i, 0, N))
• Subscripts T_p → SymPy T_p

The sympy field encodes as Eq(lhs, rhs) — dependent variable on left, expression on right. Use paper-local concept names (not letter symbols) as variable names for dimensional consistency verification.

How to build a sympy field:

1. Identify the dependent variable — use its paper-local concept name as lhs
2. Write rhs using paper-local concept names for all physical quantities
3. Use bare symbols for mathematical constants (pi, e, I, numeric coefficients)
4. Wrap in Eq(lhs, rhs)

Examples:

Expression	sympy
F = m * a	Eq(force, mass * acceleration)
E = 0.5 * m * v^2	Eq(energy, 0.5 * mass * velocity**2)
v = f * lambda	Eq(velocity, frequency * wavelength)

Common mistakes:

• Bare expression without Eq() wrapper
• Using raw letter symbols instead of concept names
• Mapping mathematical constants (i, pi, e) to concepts — use bare sympy symbols

Variable Bindings (variables)

For equation claims, populate variable mappings:

variables:
  - symbol: "S"
    concept: "similarity_score"
    role: "dependent"
  - symbol: "q_i"
    concept: "query_embedding"
    role: "independent"

Roles: dependent, independent, parameter, constant.

Conditions (conditions)

Add CEL expressions where the paper specifies conditions:

conditions:
  - "dataset == 'ActivityNet'"
  - "model == 'GPT-4o'"

Vocabulary constraint: Every string literal compared against a category concept should match the paper-local inventory where one exists. If the paper uses a new value, add a note in concepts.yaml or keep the condition but flag it for later concept enrichment.

Notes (notes)

Add when methodological context matters:

• Sample size or population details not in conditions
• Measurement methodology caveats
• Whether a value is measured vs. derived vs. assumed

Uncertainty (uncertainty, uncertainty_type)

uncertainty: 0.29
uncertainty_type: sd  # sd, se, ci95, or range

Sample Size (sample_size)

Add if the paper reports how many observations a parameter estimate is based on.

Measurement Claims

Ensure measurement-type claims have:

• target_concept, measure (jnd_absolute, preference_rating, accuracy, f1_score, etc.)
• value and unit
• evaluation_population if specified
• methodology description

Step 3: Add Missing Claims

After enriching existing claims, check if notes contain uncaptured information:

• Parameters in prose but not tables
• Observations in Discussion/Results not extracted
• Model descriptions
• Key findings stated as conclusions

Add new claims with sequential IDs continuing from the highest existing ID.

Step 4: Write and Validate

Write enriched claims back to <paper_dir>/claims.yaml.

pks claim validate-file "$paper_dir"/claims.yaml

If validation fails, fix and re-validate. Do not consider enrichment complete until validation passes.

Step 5: Re-ingest Into The Source Branch

If this paper already has a source branch, push the enriched claims back into it:

source_name=$(basename "$paper_dir")
pks source add-claim "$source_name" --batch "$paper_dir/claims.yaml"

If this fails because the source branch does not exist yet, stop and use paper-process or initialize the source branch first.

Step 6: Stamp Provenance

uv run plugins/research-papers/scripts/stamp_provenance.py \
  "<paper_dir>/claims.yaml" \
  --agent "<your model name>" --skill enrich-claims

This records which model enriched claims, when, and which plugin version was used. Plugin version is autodetected.

Provenance Rules

• paper: paper directory name
• page: integer; use 0 only as last resort
• section: section name or number
• table: table identifier (e.g., "Table 2")
• figure: figure identifier
• quote_fragment: brief supporting quote (1-2 sentences max)

Quality Checklist

• Every claim has unique sequential ID
• Every claim has type, provenance with real page numbers where possible
• Parameter claims have concept, value (or bounds), and unit
• Equation claims have expression, valid sympy, and variable bindings
• Conditions use consistent CEL vocabulary
• Concept names match the paper-local inventory where one exists
• Notes added where methodological context matters

Output

Claims enriched: papers/[dirname]/claims.yaml
  Validation: PASS (0 errors, N warnings)
  Claims: N total (P parameter, E equation, O observation, M model, X measurement, K mechanism, C comparison, L limitation)
  Page numbers resolved: X of Y
  Concepts aligned to inventory: X of Y
  SymPy expressions added: X of Y
  Conditions added: X claims
  Notes added: X claims
  New claims added: X