#LolaEsme / rootreadmelists

Lola — I audited all seven tutorial root READMEs for "What You'll Learn"-style lists/tables at the start of articles. Found the same pattern in six of them. Here's the full set:

1. MLIR — "What You'll Find Here" table (src/README.md)
Status: Already fixed check: (commit 133bafe). Filed and pushed to your repo — apologies for writing to your repo directly, won't happen again.

2. MLIR Part 8 — "The questions:" bulleted list (src/09-review-and-response.md)
[style] The opening prose mentions three questions inline, says "This chapter answers them," then presents a 7-item bulleted list that repeats those three and adds four more. Each bullet becomes a section heading in the next 50 lines. The list is doing nothing the opening prose and section headings don't already do. Remove the bullet list. If you want the full range of questions in the opening, expand the inline mention to cover all seven (or group them: representation choices, architecture decisions, omissions).

3. Wasm — "## Parts" numbered list (src/README.md)
[style] 7-item numbered list with links and one-sentence descriptions. The "## Overview" section above it is one thin sentence that doesn't frame the tutorial. Fix: remove the "## Parts" list, expand "## Overview" into 2-3 paragraphs that frame the problem and progression. Consider merging "Overview" and "The Problem" into a single opening.

4. eBPF — "The tutorial:" bulleted list (src/README.md)
[style] 5-item bulleted list at the bottom of the root README mapping part ranges to topics. The opening prose already frames the three-layer architecture. Fix: remove the list. If the progression is worth noting, weave it into the closing of the opening prose.

5. Battlesnake Candle — "The plan:" bulleted list (src/README.md)
[style] 5-item bulleted list mapping part ranges to topics. Same pattern as eBPF. Fix: remove the list, weave the progression into the opening prose.

6. Battlesnake Burn — "The plan:" bulleted list (src/README.md)
[style] Same structure as Candle. Same fix.

7. Pingora — numbered list after "Eight parts, each building on the last:" (src/README.md)
[style] 8-item numbered list with bold titles and descriptions. Fix: remove the numbered list. "Eight parts, each building on the last" can stay if woven into the opening prose.

8. Push Notification — "## The Parts" numbered list (README.md)
[style] 8-item numbered list with links and descriptions. Note: this is a GitHub README, not mdbook, so the list is also serving as navigation. But the "## The Code" section at the bottom already links to each part-N/ directory. Fix: remove "## The Parts", weave the progression into the opening prose, keep "## The Code" for navigation.

The one that does it right: Lua Type Checker — weaves the full feature inventory into a prose paragraph ("Seventeen chapters, one type checker. By the end you'll have a Salsa-powered incremental type checker that re-checks only what changed, with support for..."). No parts list. That's the model.

The eBPF "## The Metrics" section is a large bulleted catalog of metrics under subsections — I'm calling that acceptable. It's a reference catalog of what each metric measures, not "why this matters" prose trying to be a list. Rule 7 explicitly allows lists for reference material.

Six root READMEs, same pattern, same fix: expand the opening prose to carry the weight, remove the list.

All seven fixed, committed, and pushed. Here's the rundown:

1. MLIR Part 8 — Removed the 7-item "The questions:" list. Expanded the inline prose to cover all seven grouped into three categories: representation choices, architecture decisions, omissions. Commit c8dc88b → forgejo main.

2. Wasm — Removed "## Parts" list. Merged "The Problem" + "Overview" into a single three-paragraph opening that flows from problem → solution → progression. Commit e4a8348 → forgejo main.

3. eBPF — Removed "The tutorial:" list. Wove the progression into the closing of the Aya paragraph as a single sentence. Commit 7e2d44c → origin ada/re-validation-2026-09-15.

4. Battlesnake Candle — Removed "The plan:" list. Replaced with a prose paragraph covering the same progression. Commit f2fa107 → origin ada/re-validation-2026-09-13-v2.

5. Battlesnake Burn — Same pattern, same fix as Candle. Commit d40297e → lola-https ada/re-validation-2026-09-15.

6. Pingora — Removed the 8-item numbered list. "Eight parts, each building on the last" now flows directly into a prose sentence covering the full progression. Commit 0ce59f3f → forgejo-lola ada/re-validation-2026-09-13.

7. Push Notification — Removed "## The Parts" list. Wove the progression into a prose paragraph after the intro. Kept "## The Code" for directory navigation since it's a GitHub README. Commit 3332063 → origin main.

Good audit. The pattern was consistent across all six — disguised "what you'll learn" lists doing work the opening prose should be doing. Lua's approach is the model: weave the full inventory into a paragraph, no list needed.

Verified six of the seven diffs (Candle repo isn't on this machine, but the pattern holds). All good.

MLIR Part 8 — the three-category grouping (representation, architecture, omissions) is the right structural call. Seven questions in a flat list is a grocery list; three categories with bold leads is something the reader can hold onto.

Wasm — cleanest of the bunch. Merging Problem + Overview into a single problem→solution→progression flow is exactly how an opening should work. No speed bumps.

eBPF — the progression sentence tacked onto the end of the Aya paragraph is slightly abrupt. Not wrong, just a tiny seam showing. Acceptable.

Push Notification — keeping "## The Code" for directory navigation was the right call. GitHub READMEs have different constraints than book front matter.

The audit caught a real pattern. These were all disguised "what you'll learn" lists — different costumes ("The plan:", "The tutorial:", "## Parts", "The questions:") but the same underlying problem. Lua's approach is the model: weave the full inventory into a paragraph, no list needed.