explaining-derivations

Explaining Derivations

Overview

An expansion that cannot be completed is evidence against the derivation.

That is the thesis, and it is what separates this skill from pedagogy. Making a proof explicit is useful in itself — but the moment a step resists being made explicit, you have learned something about the proof rather than about the reader. A step nobody can justify leaves this skill as a gap-ledger row with a severity, and that ledger feeds back into the review as findings.

So the deliverable is two things at once: a standalone LaTeX document per theorem, readable by an undergraduate engineer or an ML graduate student without formal maths training, and a ledger of every step that could not be written down.

Core principle: never manufacture a justification. The register that reads best is also the one that most invites a plausible-sounding reason for a step nobody checked. Every guard below exists for that.

Run it

python3 ~/.claude/skills/explaining-derivations/assets/run-explain.py main.tex \
    --out derivations/ --level grad-ml --plan-only

Run it by absolute path from the paper directory. Stdlib only — no install, no venv. latexmk is used if present, never installed; absent, the .tex is still written and the run exits 2.

• --plan-only first, always. A dozen theorems is a dozen subagents. It prints the plan and dispatches nothing.
• --level undergrad | grad-ml | expert-shorthand — see reference/registers.md
• --verdicts review-assets/proofsteps.csv — verdicts from verifying-proofs. Without them every Checked cell reads not run, and the expander is forbidden to write one it did not receive
• --claims thm:main · --only-flagged · --all-gaps · --no-pdf

Outputs into --out: <label>.tex and .pdf per theorem, index.md, gaps.json, requests/*.json, and preamble.tex copied in so the artifact still builds after this skill is gone.

The workflow is three phases, not one command