Quiz Coverage Audit: Propose New Questions from Recent Changes

Goal: read what changed recently in the guide and in Claude Code itself, cross-reference against the live quiz, and propose new questions for anything with no coverage yet. This is a proposal-only workflow: never auto-add questions to the live quiz without human review.

Sources to read

1. CHANGELOG.md in this repo — [Unreleased] section plus the last 5-10 released entries, to see what guide content changed or was added recently.
2. machine-readable/reference.yaml — the guide's topic/section index (deep_dive keys), to know what's documented and where.
3. machine-readable/claude-code-releases.yaml — Claude Code's own version history (latest, releases[], breaking_summary, milestones). Focus on the most recent 10-15 versions.
4. guide/core/claude-code-releases.md — human-readable version of the same, useful for full context on a specific release.

Live quiz ground truth

The deployed quiz reads from: /Users/florianbruniaux/Sites/perso/claude-code-ultimate-guide-landing/src/content/questions/**/*.md

16 categories (directory = category_id): 01-quick-start, 02-core-concepts, 03-memory-settings, 04-agents, 05-skills, 06-commands, 07-hooks, 08-mcp-servers, 09-advanced-patterns, 10-reference, 11-learning-with-ai, 12-architecture-internals, 13-security-hardening, 14-privacy-observability, 15-ai-ecosystem, 16-agent-harness-context.

Question file schema (frontmatter + body):

---
id: NN-NNN            # category-two-digit, question three-digit
category_id: N         # 1-16
difficulty: junior|intermediate|senior|power
profiles: [junior, senior, power, pm]   # subset
correct: a|b|c|d
options:
  a: "..."
  b: "..."
  c: "..."
  d: "..."
doc_reference:
  file: guide/....md   # must exist under the guide repo root
  section: "..."
  anchor: '#...'       # optional
official_doc: https://...   # optional
---

Question text here

---

Explanation text here

YAML gotcha: any option or field value containing a colon (: ) MUST be wrapped in double quotes, or the frontmatter fails to parse (this broke the build twice during the last quiz audit, see claudedocs/quiz-audit-2026-07-08/ for the incident).

What to do

If $ARGUMENTS names a category id or slug, scope the gap analysis to that category only. If $ARGUMENTS is empty or all, cover every category.

For each category in scope:

1. Read every existing question's question text and doc_reference in that category's directory (id + question only, skip explanations, to keep this cheap) to know what's already covered.
2. Cross-reference against:
   • Any [Unreleased] or recent CHANGELOG.md entry describing a guide addition relevant to this category's topic.
   • Any claude-code-releases.yaml entry (recent versions) describing a new Claude Code feature, flag, default change, or behavior relevant to this category, that has no existing question about it.
   • Any reference.yaml deep_dive key for this topic whose linked guide section has no corresponding question.
3. Draft 2-5 NEW questions per category that fill a genuine gap (not a rephrase of an existing question). Each must:
   • Be non-trivial (tests understanding/application, not pure trivia).
   • Have exactly 4 plausible options with one verifiably correct answer (check the cited guide section yourself before finalizing).
   • Cite a real doc_reference (file that actually exists under the guide repo, section that actually supports the answer).
   • Prioritize recent (last 2-3 releases) Claude Code changes and recently-added guide sections over older, already-stable content.
4. One-line rationale per question: what gap it fills and why now (e.g. "v2.1.202 added X, no question covers it yet").

Output

Write proposals to claudedocs/quiz-coverage-audit-\{today's date\}/proposals-new-questions.md, grouped by category, formatted as ready-to-paste frontmatter + question + explanation blocks matching the schema above, each with its rationale. Do not touch any file under claude-code-ultimate-guide-landing/. Do not commit or push anything.

At the end, print a short summary: categories scanned, gaps found, questions proposed per category, and any category where the CHANGELOG/releases mention something relevant but you weren't confident enough to draft a question (name the topic instead of guessing).