mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-07-16 23:24:55 -05:00
[PR #1851] feat(staffml): link each question to recommended textbook reading (topic → chapter) #25032
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/cs249r_book#25032
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
📋 Pull Request Information
Original PR: https://github.com/harvard-edge/cs249r_book/pull/1851
Author: @farhan523
Created: 6/9/2026
Status: 🔄 Open
Base:
dev← Head:feat/staffml-book-refs📝 Commits (1)
09fc983feat(staffml): link each question to recommended textbook reading📊 Changes
13 files changed (+430 additions, -137 deletions)
View changed files
📝
interviews/staffml/src/app/plans/page.tsx(+2 -2)📝
interviews/staffml/src/app/practice/page.tsx(+2 -2)➕
interviews/staffml/src/components/BookRefCard.tsx(+71 -0)➖
interviews/staffml/src/components/ChapterLinks.tsx(+0 -36)📝
interviews/staffml/src/components/Footer.tsx(+3 -3)➖
interviews/staffml/src/data/chapter-map.json(+0 -66)📝
interviews/staffml/src/data/corpus-summary.json(+1 -1)📝
interviews/staffml/src/data/vault-manifest.json(+2 -2)➖
interviews/staffml/src/lib/chapters.ts(+0 -24)📝
interviews/staffml/src/lib/corpus.ts(+27 -0)➕
interviews/vault-cli/src/vault_cli/book_refs.py(+164 -0)📝
interviews/vault-cli/src/vault_cli/legacy_export.py(+13 -1)➕
interviews/vault-cli/tests/test_book_refs.py(+145 -0)📄 Description
Implements #1822 (Phase 1): a "go deeper" pointer from each StaffML question back into the textbook, tied to the question's topic (not its answer), derived once per topic and inherited by all ~10.7k questions.
Builds on the draft
topic_chapter_map.yaml+ design analysis fromed68fda.What changed
vault-cli (build join + link-checker)
BookRefResolverjoinstopic → chapterviaschema/topic_chapter_map.yaml, reads each chapter's display title from its.qmdH1, and link-checks every mapped chapter at build time — a mapped chapter with no.qmdsource fails the build. This turns the original "defer until mlsysbook.ai URLs stabilize" blocker into "URLs are enforced valid."book_refsis emitted as a top-level field so it rides into the summary bundle and renders synchronously (no worker fetch).corpus-summary.json: all 9,525 published questions now carrybook_refs(100% of the 87 topics mapped, 0 orphaned).staffml (UI)
BookRefCardrenders a "Learn more in the textbook" card after the attempt — primary chapter with a Volume badge + an authored why line, plus 0–2 "also see" chapters.ChapterLinks; retireschapter-map.json/chapters.ts.Fixes a live 404 bug
ChapterLinkswas already shipping per-question links (keyed oncompetency_area), but its URLs 404'd:…/contents/vol1/nn_architectures/(oldChapterLinks)…/vol1/contents/vol1/nn_architectures/nn_architectures.html(newbook_refs)The new links are topic-granular (87 vs 13), carry a why line, and are build-link-checked against the verified-200 pattern.
Pedagogy
The card is a recommended-reading pointer tied to the topic, not an answer key — it renders after the solution is revealed, so it's a consolidation/go-deeper step rather than a shortcut around the reasoning.
Tests
test_book_refs.py— resolver resolution, primary/also_see ordering,.qmdtitle extraction, link-check fails on missing chapter, standalone slug fallback, andbook_refssurvives into the summary bundle.96 passed(1 pre-existingcodegen --checkbaseline failure, unrelated — confirmed failing on a clean tree); staffmltsc --noEmitclean + vitest93 passed.Follow-ups (Phase 2/3, not in this PR)
Prerequisite-on-wrong-answer remediation; per-question
details.resourcesoverrides +kindenum; bidirectional chapter→practice links; section-level deep links once anchors are stabilized.🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.