/review-qmd <file.qmd>

Comprehensive single-file review covering: variable consistency, content quality, and reader engagement.

Usage

/review-qmd knowledge/appendix/incentive-alignment-bonds-paper.qmd
/review-qmd economics.qmd

If no file specified, ask which file to review.

Phase 1: Generate Preview

cd E:/code/obsidian/websites/disease-eradication-plan
.venv/Scripts/python.exe scripts/preview-qmd-with-variables.py <file> -o _analysis/<basename>-preview.md
.venv/Scripts/python.exe scripts/preview-qmd-with-variables.py <file> --numbers-only

Read preview to understand rendered state. Note inconsistencies (e.g., "$2.4T" vs "$2.72T").

Phase 2: Variable Audit

REPLACE with variables:

• Core metrics: military spending, treaty funding, DALYs, household wealth, war costs
• Calculated values: BCR, mechanism costs/benefits, peace dividend
• Any value appearing multiple times

KEEP hardcoded:

• Citation-specific data (Copenhagen Consensus BCRs, study figures)
• Illustrative examples, calibration parameters
• 1% treaty concept, years in citations

Variable lookup:

grep -i "keyword" _analysis/parameter-summary.md
grep "value_pattern" _variables.yml

Key variables:

Replace with _latex versions for $$ blocks containing calculations.

Check for useful auto-generated charts:

# List variables used in file
grep -o "{{< var [a-z_]* >}}" <file> | sed 's/{{< var //;s/ >}}//' | sort -u

# For each variable, check if charts exist in knowledge/figures/
ls knowledge/figures/*<variable_name>*.qmd

Charts available per calculated variable:

• tornado-<var>.qmd - Sensitivity analysis (which inputs matter most)
• mc-distribution-<var>.qmd - Monte Carlo probability distribution
• exceedance-<var>.qmd - Probability of exceeding thresholds
• sensitivity-table-<var>.qmd - Regression coefficients

Add charts where they enhance understanding - especially for key metrics like ROI, BCR, costs. Include with:

{{< include ../figures/tornado-<variable_name>.qmd >}}

Phase 3: Content Quality Review

Read through the preview and evaluate:

Clarity & Accessibility

• Plain English summaries at section starts for non-technical readers
• Jargon explained on first use (define mechanism design, Nash equilibrium, BCR, etc.)
• Concrete examples before abstract formulas
• Visual aids referenced where helpful (figures, tables, infographics)

Engagement & Persuasion

• Strong opening hook - Does the intro grab attention? Lead with the problem/stakes
• Emotional resonance - Connect to human impact (lives saved, suffering prevented)
• Vivid comparisons - Make abstract numbers concrete ("enough to fund X hospitals")
• Call to action - Clear next steps for different audiences (investors, policymakers, researchers)

Rigor & Credibility

• Claims have citations - Every factual claim backed by source
• Uncertainty acknowledged - Confidence intervals, limitations stated
• Counterarguments addressed - Steel-man objections, then refute
• Math checks out - Calculations internally consistent

Flow & Structure

• Logical progression - Each section builds on previous
• Transitions - Clear connections between ideas
• Scannable - Headers, bullets, bold key points for skimmers

Cut the Garbage

• Redundancy - Same point made multiple times? Consolidate (pre-render validation detects duplicate _latex vars automatically)
• Filler phrases - "It is important to note that..." → delete
• Weak qualifiers - "somewhat", "fairly", "quite" → remove or strengthen
• Orphaned content - Sections that don't connect to main argument
• Over-explanation - Reader got it the first time
• Defensive hedging - Excessive caveats that undermine confidence

Tone

• Confident but not arrogant - State conclusions clearly, acknowledge limits
• Urgent but not alarmist - Convey stakes without hyperbole
• Technical but accessible - Expert credibility with lay readability
• No "consultantly" language - Avoid buzzwords, empty phrases

Publication Readiness

• No implementation code - Python/SQL → pseudocode or math notation, link to repo
• Math notation - forwardpearsoncorrelationcoefficient → $r{forward}$
• Proper tables - No ASCII art (═══, ───) - use markdown tables
• Appendix placement - Move detailed algorithms/schemas to appendix or supplementary

Phase 4: Make Improvements

Use Edit tool to fix identified issues. Track changes with TodoWrite.

Common fixes:

• Add "The short version:" summaries to dense sections
• Replace jargon: "mechanism design" → "mechanism design (designing rules so selfish choices create good outcomes)"
• Add concrete examples before formulas
• Strengthen weak openings with stakes
• CUT: redundant paragraphs, filler phrases, weak hedging, over-explanation
• Add missing citations with {{< var variable_cite >}}
• Replace $$ blocks with {{< var variable_latex >}}

Phase 5: Validate

Run pre-render validation to catch automated issues:

.venv/Scripts/python.exe scripts/pre-render-validation.py 2>&1 | grep -A2 "<filename>"
.venv/Scripts/python.exe scripts/preview-qmd-with-variables.py <file> --line-range "1-50"

Automated checks include:

• [MISSING: variable] - undefined variables
• Duplicate _latex variables (redundant equations)
• Broken links and anchor IDs
• Missing citations and imports
• Unclosed code blocks
• Em-dashes (should be commas/periods)

If duplicate _latex variables found:

1. Review both occurrences - are they truly redundant?
2. If redundant, remove the duplicate (keep the one in better context)
3. If both needed, consider if they're explaining different aspects

Phase 6: Report

## Review Complete: <filename>

### Preview: `_analysis/<basename>-preview.md`

### Variable Replacements
| Line | Old | New Variable |
|------|-----|--------------|

### Content Improvements
- [x] Added plain English summary to Section X
- [x] Fixed weak opening in intro
- [x] Added concrete example for BCR concept

### Kept Hardcoded (Intentional)
- Copenhagen Consensus data, calibration params, 1% treaty

### Validation: PASSED

Rules

1. Generate preview FIRST - understand before editing
2. Track changes with TodoWrite
3. Semantic match required - same number can mean different things
4. NEVER replace 1% treaty concept
5. Skip citation-specific data
6. Run validation AFTER changes
7. Improve engagement, not just accuracy