latex-equation-audit

Systematically find calculated variables that have corresponding _latex equations and add them where appropriate. Uses Ralph Loop for iterative processing.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The LaTeX Equation Audit skill systematically enhances technical documentation by identifying calculated variables and inserting their corresponding LaTeX equations. Utilizing an iterative Ralph Loop, it scans QMD files to ensure that complex data points are supported by clear mathematical formulas, significantly improving the clarity, transparency, and professional quality of technical reports and research papers.

Use Cases

  • Scientific & Academic Publishing: Automatically insert LaTeX formulas into research papers to explain the derivation of calculated results and improve reader comprehension.
  • Financial & Economic Reporting: Enhance fiscal analysis documents by placing mathematical equations near key performance indicators and calculated metrics for better auditability.
  • Documentation Consistency Audits: Perform project-wide scans to ensure every instance of a calculated variable is accompanied by its mathematical definition, maintaining a high standard of documentation.
  • Educational Material Development: Improve the readability of technical tutorials and textbooks by providing visual mathematical context for all variables used in the prose.
namelatex-equation-audit
descriptionSystematically find calculated variables that have corresponding _latex equations and add them where appropriate. Uses Ralph Loop for iterative processing.

Ralph Loop: LaTeX Equation Audit

This skill starts a Ralph Loop session to systematically find calculated variables from _variables.yml that have corresponding _latex equations, and add those equations where contextually appropriate in QMD files.

Purpose

Many calculated parameters have auto-generated LaTeX equations (e.g., dfda_cures_per_year has dfda_cures_per_year_latex). When a calculated variable is used in text, adding the corresponding LaTeX equation nearby can help readers understand the calculation. This audit finds opportunities to add these equations.

Usage

Just run /latex-equation-audit to start. Optional arguments:

  • /latex-equation-audit - Full project audit (default: 50 iterations max)
  • /latex-equation-audit economics.qmd - Single file mode (5 iterations max)
  • /latex-equation-audit --max 100 - Custom iteration limit

How It Works

  1. Setup: Extracts all _latex variable names from _variables.yml
  2. For each _latex variable: Finds the base variable name (strip _latex suffix)
  3. Searches QMD files for uses of the base variable {{< var base_name >}}
  4. Checks context: Is this a good place for the equation?
    • Good: After introducing a calculated value, in "How it works" sections, near formulas
    • Bad: In lists, tables, passing mentions, already has equation nearby
  5. Adds equation: Inserts {{< var base_name_latex >}} on new line after variable use
  6. Tracks progress in _latex-equation-audit-progress.md

Start Ralph Loop Now

To begin, invoke the Ralph Loop skill with this prompt:

/ralph-loop --max-iterations 50 --completion-promise "ALL_LATEX_AUDITED" Systematically find calculated variables that have _latex equations and add them where appropriate in QMD files.

SETUP (First Iteration):
1. Extract all _latex variable names: grep "_latex" _variables.yml | grep -v "^#" | cut -d'"' -f2 | sort > _latex-vars-list.txt
2. Count total: wc -l _latex-vars-list.txt
3. Create _latex-equation-audit-progress.md with all _latex vars listed as unchecked
4. Get list of QMD files: find knowledge -name "*.qmd" -type f | grep -v "_build_temp" | sort

EACH ITERATION:
1. Pick next unchecked _latex variable from progress file
2. Extract base name (e.g., dfda_cures_per_year_latex -> dfda_cures_per_year)
3. Search QMD files for {{< var base_name >}} usage
4. For each occurrence:
   a. Check if _latex version already exists within 10 lines
   b. If not, review context:
      - GOOD contexts (add equation):
        * After introducing/explaining the value
        * In methodology/calculation explanation sections
        * Where the calculation formula adds understanding
        * After prose that describes how something is calculated
      - BAD contexts (skip):
        * In bullet lists or table cells
        * Passing mentions (not explaining the calculation)
        * Already has equation within 10 lines
        * In footnotes or asides
   c. If appropriate, add {{< var base_name_latex >}} on new line after variable
5. Mark variable as checked in progress file
6. Record any additions made

COMPLETION:
When all _latex variables checked, write summary to _latex-equation-audit-report.md:
- Total _latex variables reviewed
- Number of equations added
- Files modified
- Variables with no usages found
Output: ALL_LATEX_AUDITED

RULES:
- Process ONE _latex variable per iteration
- NEVER modify _build_temp/ files
- NEVER modify parameters-and-calculations.qmd (source of truth)
- NEVER add to tables, lists, or code blocks
- Always add equation on its own line
- Leave blank line before and after equation for readability
- Skip references.qmd, futures/ chapters, vision.qmd

CONTEXT EXAMPLES:

GOOD - Add equation here:

The dFDA would enable {{< var dfda_cures_per_year >}} new cures annually. This is calculated based on the acceleration multiplier applied to baseline cure rates.

After edit:

The dFDA would enable {{< var dfda_cures_per_year >}} new cures annually. This is calculated based on the acceleration multiplier applied to baseline cure rates.

{{< var dfda_cures_per_year_latex >}}


BAD - Do NOT add equation here:

Key benefits include:

  • {{< var dfda_cures_per_year >}} additional cures per year
  • {{< var peace_dividend_annual >}} in savings
(equations don't belong in bullet lists)

Single File Mode

For a quick single-file audit:

/ralph-loop --max-iterations 5 --completion-promise "FILE_COMPLETE" Check for _latex equation opportunities in knowledge/economics/1-pct-treaty-impact.qmd. For each calculated variable used, check if _latex version exists nearby. If not and context is appropriate, add it. Output FILE_COMPLETE when done.

Files to Skip

The audit automatically excludes:

  • _build_temp/ - Build artifacts
  • references.qmd - Citation database
  • parameters-and-calculations.qmd - Parameter definitions (source of truth)
  • futures/ - Fictional scenarios
  • vision.qmd - Vision statement (narrative focused)

Contextual Decision Making

When to ADD the equation:

  1. Calculation explanations: "This is calculated by multiplying X by Y"
  2. Methodology sections: Explaining how values are derived
  3. After standalone value introduction: "The total cost is {{< var X >}}."
  4. ROI/benefit discussions: Where showing the math adds credibility

When to SKIP:

  1. Lists/tables: Equations break list formatting
  2. Passing mentions: "...saving {{< var X >}} annually..."
  3. Already has equation: Within 10 lines above or below
  4. Narrative flow: Would interrupt storytelling
  5. Repeated values: Only add equation on first substantive mention
  • /cancel-ralph - Stop an active Ralph loop
  • /ralph-hardcoded-audit - Find hardcoded values to replace with variables
  • /pre-render-validate - Validate all QMD files before render