PROJECT: Reorganise lecture improvements into `project-lecture-improvements` with live status tracking (retiring #173 as a checklist)

[mmcky]

Summary

Retire #173 as a hand-maintained checklist and reorganise the lecture review & modernisation program into a project-lecture-improvements coordination repository, with a machine-refreshed JSON catalog as the live status layer — following the pattern already established by project-translation + status-translations and project-style-guide.

The prompt for this is @jstac's observation: "it's easy for something like #173 to fall out of date — e.g. we decide against a conversion but fail to update that issue — and also fail to have sufficient context for RAs." That is exactly right, and it is now measurable. A checkbox list in an issue body has no way to record a decision (we looked and decided not to convert), no way to notice that the world moved underneath it, and nowhere to put the per-lecture context an RA needs before picking up work.

Why now — #173 has measurably drifted

Audit of the #173 body against live GitHub state, run 2026-07-22. The list holds 129 lecture rows (79 intermediate, 50 advanced), of which 7 are ticked, 42 carry an @handle, 25 carry a PR link, and 87 have neither an owner nor a PR — i.e. two-thirds of the list has been inert since it was written in August 2025.

Drift	Count	Detail
Merged PR, still shown unticked	7	ar1_turningpts, mix_model, kesten_processes, mccall_correlated, mle, arellano, lucas_model
Closed/abandoned PR, still presented as in-flight	5	ar1_bayes, kalman, career, jv, markov_asset
Slug no longer matches a file in the repo	8	cake_eatingproblem, cake_eating_numerical, optgrowth, optgrowth_fast, coleman_policy_iter, egm_policy_iter, ifp, mccall_correlated — renamed in the os_* / ifp_* reorganisation
Lectures in the repo but absent from the list	~60	46 in lecture-python.myst, 14 in lecture-python-advanced.myst (excluding intro/status/troubleshooting/zreferences)
Ticked with no PR recorded	2	mccall_model_with_separation, mccall_fitted_vfi — no evidence trail

The five abandoned PRs are the failure mode @jstac named: work was attempted, a call was made, and the list still reads as "in progress, assigned". Whatever the reason was, it is not written down anywhere a new RA can find it — so the next person either redoes it or avoids it without knowing why.

Of the 28 PRs referenced in #173: 13 merged, 5 closed, 10 still open (9 open + 1 draft), the oldest open since 2025-08-30.

The proposal

1. project-lecture-improvements — the coordination home

A project-* repo under QEP-3: decides and records why; private; goal-scoped; no production code. It carries the narrative that an issue body cannot hold:

• ROADMAP.md / PLAN.md — what the program is, phases, exit criteria, what "improved" means per pass (typos & mathos, style-guide compliance, JAX conversion, exercise coverage).
• DECISIONS.md — the decision register, including decided against calls with a reason and a date. This is the single highest-value artefact and the direct answer to the drift above.
• RA onboarding — the workflow currently buried in the Lecture Improvement Project #173 preamble (assign yourself, one PR per lecture, DRAFT first, tag reviewers, sync zh-cn), plus per-lecture briefs: what this lecture is, why it is a candidate, what "done" looks like, known traps.
• manifest.yml + make sync — the QEP-3 minimal command bench over lecture-python.myst, lecture-python-advanced.myst, lecture-jax, lecture-python-intro.
• status/ — the catalog below, incubating here until it earns its own repo.

Suggested access: private, with the lecture-review-modernization team granted write, so RAs read the same source the maintainers do.

2. The status layer — a JSON catalog, not a checklist

One row per lecture, keyed {repo}/{slug}, seeded from lectures/*.md so the corpus is complete by construction and renames surface as diffs rather than silently rotting. Modelled on status-translations' data/latest.json + data/history/ contract.

Field	Owner	Notes
repo, slug, series, chapter	derived	seeded from the repo tree; a slug that disappears is flagged, not lost
state	human	see the state list below
decision, decision_reason, decision_date, decided_by	human	the "we decided against it" record — required whenever state is declined
owner	human	current RA, or empty
prs	derived	every PR touching lectures/{slug}.md, with live open/merged/closed state
issues	derived	open issues titled [{slug}] … — the repos already use this convention
jax_candidate, jax_signals	derived + human	grep for numba/@jit/@njit/prange/vectorize + explicit maintainer override
styleguide_state	derived	from action-style-guide / audit.2026-05.style-guide
last_touched, last_verified	derived	last commit to the lecture file; last time a human confirmed the row
notes	human	the RA context

Proposed states: candidate · assigned · in-review (PR open) · done (PR merged) · declined (looked at, decided against — reason required) · not-applicable (e.g. pure-prose lecture, no code to accelerate) · blocked (e.g. upstream fix pending, chapter under active authorship by Tom).

declined and not-applicable are first-class terminal states. A checkbox list has exactly two states and that is why it drifts.

3. Derived vs human — the anti-drift mechanism

A nightly collector recomputes everything in the derived column from public GitHub state, so PR/issue/rename churn can never make the catalog stale; humans only ever own the judgement fields. That split is what makes status-translations reliable, and it applies cleanly here. The dashboard then answers, per series: how much of the corpus has had a review pass, what is in flight and how long it has sat, what was declined and why, and where the JAX candidates actually remain.

Per QEP-3's boundary rule ("a dashboard may incubate as hand-maintained tables inside a project repo; once its numbers are collected automatically on a cadence it graduates to a status-* repo named for the domain it measures"), the catalog starts in project-lecture-improvements/status/ and graduates to status-lecture-improvements once the collector is on a cron. Keeping it separate from status-lectures preserves that repo's domain (build/environment configuration, #321); the alternative — an editorial-progress page inside status-lectures as the umbrella "how are the lectures doing" URL — is a reasonable call to make instead, and is listed as a decision below.

Onboarding inventory

What moves into, or gets indexed by, the new repo:

Asset	Volume	Disposition
#173 body (the lecture list)	129 rows	Seeds the catalog; corrected against the real file tree and PR states
#173 preamble (RA workflow)	—	Becomes CONTRIBUTING.md / RA onboarding doc
PRs referenced from #173	28 (13 merged · 10 open · 5 closed)	Auto-linked; the 10 open ones get a triage pass — land, refresh, or close with a recorded reason
The 5 abandoned PRs	5	Each needs a declined/blocked decision written down, or a fresh owner
lecture-python.myst improvement issues	62 open (excl. automated reports), incl. jax-conversion, improve, good first issue	Indexed per lecture via the [slug] title convention
lecture-python-advanced.myst issues	27 open	Same; includes the [amss] JAX family and the style-guide review issue lecture-python-advanced.myst#261
lecture-python-intro issues	67 open, of which 32 are labelled improve or reading-group-2023/2024	The largest existing improvement backlog in the org — same program, currently untracked by #173
lecture-jax issues	29 open	The conversion target side of the ledger
lecture-review-modernization team	10 contributors tagged in #173	Ownership + access

Related meta issues to cross-link (not absorb): #332 Projects as the PM/reporting layer · #321 environment & config reporting · #299 NumPy Generator sweep · #320 action-code-style · #341 code-figure directive · #333/#334 repo renames (they will move slugs under the catalog) · #310 Custom Course Builder, which already cross-references #173.

Relationship to meta#332

No conflict, and no duplication: issues stay the source of truth in their home repos, GitHub Projects stays the portfolio view for humans, and the catalog is the corpus-complete view — one row per lecture, including the ~60 lectures nobody has opened an issue about. Projects cannot represent "this lecture exists and has never been looked at", which is most of the work. The Lectures workstream in #332 can pull its status update straight from the catalog.

Proposed sequence

• Agree the repo name and the status-repo question (below)
• Create project-lecture-improvements (private; lecture-review-modernization team → write)
• Scaffold ROADMAP.md, PLAN.md, DECISIONS.md, CONTRIBUTING.md, manifest.yml + bench
• Seed status/catalog.json from the repo trees, merged with the Lecture Improvement Project #173 rows and live PR state
• Triage the 10 open PRs and the 5 abandoned ones; write the decisions into DECISIONS.md
• Reconcile the 8 stale slugs against the os_* / ifp_* reorganisation
• Write the collector (derived fields, nightly) — reuse status-translations/collector structure
• Index the ~185 open non-automated issues across the four repos into the catalog by [slug]
• Publish the dashboard; graduate to status-lecture-improvements when the cron is green
• Replace Lecture Improvement Project #173's body with a pointer to the new home and close it
• Post an update to the lecture-review-modernization team pointing at the new workflow

Decisions needed

1. Repo name — project-lecture-improvements (plural, proposed) vs project-lecture-improvement. Cosmetic; picking one unblocks the rest.
2. Scope — intermediate + advanced only (the Lecture Improvement Project #173 scope), or include lecture-python-intro? Intro carries the single largest improvement backlog (32 issues labelled improve or reading-group-*) and is the same kind of work, so including it is the recommendation.
3. Status home — own status-lecture-improvements repo on graduation (recommended, keeps domains clean), or an editorial page inside status-lectures as a single lectures umbrella.
4. Visibility — private like the other project-* repos (recommended, QEP-3 default), noting that a public catalog would let outside contributors self-serve; the dashboard can be published publicly either way.

Success criteria

• Every lecture in the covered series has a row, and no row can silently misrepresent PR or issue state.
• Every declined conversion has a reason and a date attached to it.
• An RA can pick a lecture, read its brief, and start work without asking anyone what the context is.
• "How is lecture modernisation going?" is answerable from one URL, without anyone updating a checklist.

---

Audit figures in this issue were computed on 2026-07-22 from the #173 body and live GitHub API state; the reconciliation script is the seed for the catalog collector.