Pilot Review Guide (historical)

Historical document. This guide was written when only the two pilot chapters (Ch 2 and Ch 15) existed, to collect the feedback that shaped the chapter template (docs/PROPOSAL.md §6.1). All 25 chapters are now available; start from README.md and the syllabus in chapters/README.md. The setup and review steps below are kept as written at the time.

Two pilot chapters are ready. Please review them before the remaining 23 chapters are built. Your feedback changes the chapter template, so it applies to every later chapter.

• Ch 2 · Grammars & Top-Down Parsing (chapters/02-top-down-parsing/)
• Ch 15 · Control-Flow Analysis: Dominance & Loops (chapters/15-dominance-and-loops/)

Both were built to the width-and-depth contract (docs/PROPOSAL.md §6.0). They were verified against LLVM 23 on Linux here and in CI on macOS (Apple Silicon, Homebrew) and Ubuntu.

1. Set up (≈15 min, macOS)

brew install llvm lit googletest ninja cmake     # LLVM 23.x
git clone -b claude/lucid-clarke-g8eb4h https://github.com/FlickerSoul/LLVMLearning && cd LLVMLearning
./course doctor                                  # checks everything, tells you what to fix

See docs/setup/macos.md if anything goes wrong.

2. What to try (≈1–2 h per chapter, skim is fine)

Step	Ch 2	Ch 15
Read the technique map	chapters/02-top-down-parsing/README.md	chapters/15-dominance-and-loops/README.md
Read one or two lessons fully	lessons/03-ll1-tables-and-conflicts.md, lessons/06-llk-and-all-star.md	lessons/01-dominator-algorithms.md (iterative → CHK → Lengauer–Tarjan → Semi-NCA)
Take the quiz	./course quiz 2	./course quiz 15
Drill + worked solution	./course drill ll1-table then --solution	./course drill lengauer-tarjan then --solution
Flashcards	./course flash 2	./course flash 15
Run the tests on the empty skeleton	./course test 2: every failure names its exercise, e.g. TODO(ch02): E3	./course test 15
Implement one exercise	E1 in exercises.md (nullable/FIRST/FOLLOW)	E2 (Cooper–Harvey–Kennedy)
Peek at a solution	solutions/labs/ch02-ll1-toolkit/	solutions/labs/ch15-dominance/
See all tests pass with solutions	./course test 2 --solution	./course test 15 --solution

3. Feedback I need

Answer any of these. Short answers are fine.

1. Depth: too much, about right, or too little? Is there a lesson where the traced worked examples felt too long or too short?
2. Width: did the technique map cover what you expected? Anything missing, or anything that should be dropped?
3. Lesson format: do the nine fixed sections per technique help, or feel repetitive? Would you prefer fewer, larger lessons, or more, smaller ones?
4. Theory tests: quiz length (30 questions), difficulty, and answer formats. Are the drills with worked solutions useful for memorizing?
5. Flashcards: 75 per chapter. Too many or too few?
6. Exercises: is the difficulty right? Are the hints helpful? Should more of the comparison labs be required instead of optional (★)?
7. Tests: are the failure messages clear? Would you like more LLVM-as-oracle testing, or less?
8. Setup and tooling: any friction on your Mac?
9. Anything else to change in the template before the other 23 chapters are written.

When you're ready, send your feedback and say "build the remaining chapters". The template is updated first, then the chapters are built in waves (see docs/PROPOSAL.md §7).