writing

Learn by Reasoning, and learning game theory with it

I read a fair amount of economics and finance, and most of it does not stick. I follow the argument while I am reading, nod along, and a week later I could not explain it to anyone. So I built a small tool to make me do the part I was skipping: learn-by-reasoning, a Claude Code plugin, published today on GitHub under the MIT licence.

what it is

You give it a PDF — a book or a set of lecture notes — and it turns it into a chapter-by-chapter course. Then, instead of explaining the material at you, it teaches each concept in three steps:

  1. A problem first. You get a small problem that needs the concept, and you work through it before any explanation. No hint, no definition, not even the concept's name if the name would give the answer away. Where it can, the problem comes from the book's own examples and exercises.
  2. Then the explanation, in plain words, starting from your attempt: what in it was right and where it went off. You choose whether you want it formal (the definition, stated plainly) or as a story (a concrete situation that carries the idea).
  3. Then a teach-back. You explain the concept in your own words, as if to a friend who has not met it. Claude probes the gaps with questions rather than correcting you, and then gives you a fresh case to apply it to. The concept counts as done only when your explanation states the core idea correctly and you apply it correctly to the new case. "Got it" or "makes sense" does not pass.

A concept whose teach-back does not hold up is marked shaky, and the gap is written down. When you come back after a break, a short warm-up quiz on earlier concepts comes first — shaky ones before the rest — and then the session carries on where you stopped.

The idea behind it is simple: reading gives you the feeling of understanding, and being asked to solve something and then explain it is what tests whether the feeling is right.

how to use it

It needs Claude Code, Python 3 (standard library only) and pdftotext, which comes with Poppler (brew install poppler). The PDF needs a text layer; scanned PDFs are not supported yet.

Inside Claude Code, install it from the repository:

/plugin marketplace add remicaesar/learn-by-reasoning
/plugin install learn-by-reasoning@learn-by-reasoning

Restart Claude Code, then point it at a PDF:

/learn-by-reasoning:start "<path to a PDF>"

That reads the material and shows you a plan — the book's chapters in the book's order, with the concepts inside each — and lets you skip, merge, rename or add parts before anything is written. When you are happy with it, it creates a folder for the book under ~/learning/. From then on you work inside that folder:

cd ~/learning/<book-folder> && claude
/learn-by-reasoning:study
/learn-by-reasoning:progress

study runs a session: the warm-up quiz if one is due, then the next concept. progress prints a map of the book in the terminal.

The book's folder holds two plain Markdown files. plan.md has the chapters, their pages, and every concept with its state (not started, in progress, shaky, done); it only points at your PDF and never copies it. journal.md keeps your own explanations and the mistakes behind any shaky concept, so later sessions can aim at them. Both survive uninstalling the plugin.

how I am using it

The first book is Omer Tamuz's Undergraduate Game Theory Lecture Notes. I am not a game theorist; I am reading them as an outsider, which is exactly the situation the plugin is for.

This is the plan the plugin built from the notes, ten chapters and 58 concepts:

  1. What is a Game?
  2. Finite extensive form games with perfect information
  3. Strategic form games
  4. Knowledge and belief
  5. Auctions
  6. Extensive form games with chance moves and imperfect information
  7. Repeated games
  8. Social learning
  9. Better response dynamics and potential games
  10. Social choice

And this is where I am, exactly as progress prints it today:

Undergraduate Game Theory Lecture Notes
░░░░░░░░░░░░░░░░░░░░ 0 of 10 chapters · 0 of 58 concepts

 ▶ Ch 1   What is a Game?                                           0/3 concepts
          ▶ Players, choices, outcomes, preferences  ← you are here
          · What makes an interaction strategic
          · Solution concepts vs. the game itself
 · Ch 2   Finite extensive form games with perfect information      0/8 concepts
 · Ch 3   Strategic form games                                      0/9 concepts
 · Ch 4   Knowledge and belief                                      0/8 concepts
 · Ch 5   Auctions                                                  0/6 concepts
 · Ch 6   Extensive form games with chance moves and imperfect in…  0/7 concepts
 · Ch 7   Repeated games                                            0/6 concepts
 · Ch 8   Social learning                                           0/3 concepts
 · Ch 9   Better response dynamics and potential games              0/4 concepts
 · Ch 10  Social choice                                             0/4 concepts

Next session: Players, choices, outcomes, preferences

That is to say: I have barely started. The first concept — what a game is made of: players, their choices, the outcomes, and what each player prefers — is in progress, and nothing is checked off yet. The one thing recorded so far is my answer to how I want things explained, which was both: the formal version and the story.

I will write again once there is something real to report — whether the teach-backs hold up, and whether this works any better than reading did.

The code and the install instructions are at github.com/remicaesar/learn-by-reasoning.