benithors/agent-scripts/codebase-quiz

Codebase Quiz

Purpose

Turn real implementation work into an evidence-backed learning experience.

The result is one polished HTML page that:

• teaches the feature through compact visual sections;
• distinguishes measured facts from interpretation;
• quizzes the user inside the page;
• explains every answer;
• reveals the correct option clearly after a wrong answer; and
• is opened and tested before handoff.

This is not a generic quiz generator. The questions and teaching material must come from the actual code, tests, documentation, history, and available prior-session evidence.

Interaction Contract

1. If the user has not supplied a topic, ask exactly one opening question in the user's language. In English, use:

> What should I quiz you about?

1. Wait for the answer before researching.
2. If the topic is already present in the invocation, do not ask it again.
3. Resolve ordinary ambiguity from the repository and available history. Ask another question only when different interpretations would materially change the artifact.
4. Match the user's language for teaching copy. Keep code, comments, selectors, and test text in English unless repository rules require otherwise.

Phase 1: Establish the Evidence

1. Confirm the working context

• Identify the repository, branch, and relevant feature boundary.
• Read every applicable AGENTS.md before acting.
• Check the worktree and preserve unrelated changes.
• Treat research as read-only. Do not modify product code unless the user separately requests it.

2. Inspect the current implementation

Search with rg or rg --files first. Read the smallest useful set of:

• implementation files;
• tests and feature files;
• benchmarks or measurement artifacts;
• architecture and operational documentation;
• configuration that changes runtime behavior; and
• user-facing components that expose the feature.

Trace the whole behavior, not only the file whose name matches the topic. For a performance feature, for example, follow the path from interaction to authentication, server work, data readiness, rendering, and measurement.

3. Reconstruct the change history

Use the strongest available sources:

1. current code and tests;
2. current benchmark artifacts;
3. relevant git diffs, commits, and blame;
4. prior coding-session summaries or transcripts;
5. memory or screen-history tools when available.

Use prior sessions to recover intent, rejected approaches, and debugging context. Verify drift-prone claims against the current checkout whenever practical. Clearly label anything that remains memory-derived or inferred.

If prior-session evidence is unavailable, continue from current code and git history. State that limitation instead of inventing historical intent.

Do not perform a broad history dump. Search by feature names, symbols, routes, metrics, commit messages, and distinctive error text.

4. Build an internal evidence map

Before writing, be able to map each teaching claim to evidence:

claim -> current file/test/benchmark -> historical context -> confidence

Do not put invented numbers, unverified causes, or generic best practices into the page as though they describe the implementation.

Phase 2: Build the Teaching Model

Choose the causal model that matches the feature. Do not force every topic into a performance narrative.

Common models include:

performance
symptom -> representative metric -> bottleneck -> change -> result -> guardrails
 
stateful feature
actor + input -> state transition -> persisted effect -> visible output -> invariant
 
architecture or integration
request/event -> owner -> boundary -> dependency -> response -> failure handling
 
reliability or security
failure/threat -> detection -> containment -> recovery -> proof
 
refactor
old responsibility -> new ownership -> preserved behavior -> tradeoff

The explanation should be deep but compressed. Prefer a precise diagram, comparison, or timeline over several paragraphs.

Cover only the concepts the user needs to reason about this feature, such as:

• the initiating actor, event, or user-visible behavior;
• the old behavior and its ownership or scope;
• the new behavior and its ownership or scope;
• the important state, data, request, or control-flow transition;
• why the change works;
• what behavior or invariant is deliberately preserved;
• measured outcomes when trustworthy measurements exist; and
• limitations, guardrails, tradeoffs, or failure modes.

Phase 3: Create the HTML Experience

Create a standalone HTML page. If the host has an inline-visualization contract, keep its editable fragment as the source and render a standalone copy from it.

Artifact location and data safety

• Prefer the host's designated visualization or artifact directory outside the product repository.
• If no artifact directory exists, use a uniquely named temporary directory or a path supplied by the user. Write inside the product repository only when the user explicitly asks.
• Never overwrite an existing artifact without confirming that it belongs to this task.
• Keep the page self-contained with inline CSS, JavaScript, and data. Do not require a server, network fetch, or remote runtime dependency for core behavior.
• Treat code excerpts, commit text, and session-derived strings as untrusted content. Insert dynamic text with textContent or escape it correctly; serialize data safely instead of interpolating raw text into HTML or JavaScript.
• Never place secrets, tokens, private transcript passages, or sensitive local data in the artifact.

Required page structure

1. Outcome metrics

• Show at most three compact metrics.
• Include only evidence-backed numbers that materially explain the feature.
• Omit the row when there are no trustworthy numeric outcomes.

1. Section controls

• Use three to five feature-specific sections plus Quiz.
• Examples are Measure, Auth path, Navigation UX, and Benchmark safety; do not reuse these names when the feature needs different concepts.

1. Section explanation

• Every section must display one short explanation above its visual.
• Prefix it with a compact accent badge naming the current concept.
• Keep the explanation to the minimum needed to interpret the visual.

1. One dominant visual per section

• Use before/after bars for measured comparisons.
• Use a flow diagram for ownership, requests, caching, or data paths.
• Use a timeline for interaction and readiness behavior.
• Use a boundary flow for safeguards and failure containment.
• Choose the smallest visual that explains the relationship. Do not decorate empty space.

1. On-page questionnaire

• The questions must live inside the HTML page, not only in chat.
• Show one question at a time.
• Default to the Quiz section being open when the page is delivered.

1. Compact evidence trail

• Include the relevant paths, benchmark artifact names, or commits without overwhelming the teaching flow.
• Never expose secrets, tokens, private session content, or irrelevant local paths.

Quiz content

• Default to six questions unless the feature's scope justifies fewer or more.
• Use four options with exactly one correct answer.
• Make options mutually exclusive, unambiguous, and comparable in specificity.
• Vary the correct-answer position; do not make answer order itself a clue.
• Test reasoning about behavior, scope, measurement, tradeoffs, and safety—not filename trivia.
• Build distractors from plausible misconceptions found during research.
• Keep each question answerable from the teaching sections.
• Add a concise explanation that says why the correct model is correct.
• Keep an internal evidence reference for each question and explanation.

Quiz behavior

• Disable Check answer until an option is selected.
• After checking, lock the options for that question.
• Keep the selected answer visible.
• Show an explanation below the options.
• Advance only when the user chooses Next question.
• Show question progress, a restrained progress bar, and the current score.
• End with the final score and a prompt to revisit the relevant teaching sections.

When the selected answer is wrong:

• retain the wrong selection;
• render the correct option in accessible green;
• append the visible label ✓ Correct answer to that option; and
• explain the misconception.

Color must not be the only signal. The text label and checkmark are mandatory.

Visual Direction

Use a quiet, evidence-first design.

• Keep the main surface neutral and spacious.
• Use one primary accent for selected controls, progress, and the improved/current series.
• Use at most one contrast series for before or comparison data.
• Reserve green for positive outcomes and correct-answer states.
• Reserve the destructive color for wrong-answer feedback that needs attention.
• Use small dots, badges, and data marks for accents; do not color every card or heading.
• Do not use rainbow palettes, decorative gradients, oversized titles, glass effects, or ornamental dashboards.
• Keep mappings stable and pair every color meaning with text, shape, or position.
• Use theme-aware variables so light and dark modes remain readable.

Accessibility and Responsive Behavior

• Use semantic section, fieldset, legend, label, button, and progress elements.
• Use native radio inputs and preserve keyboard navigation and focus styles.
• Announce feedback and score changes with an appropriate live region.
• Associate every input and label with matching id and for values.
• Support 736px desktop width and reflow cleanly down to 320px.
• Wrap controls and long answers. Never clip text or introduce horizontal page scrolling.
• Never communicate correctness with color alone.

Verification

Do not call the artifact complete until all of these pass:

1. Recheck every factual claim against the evidence map.
2. Validate every question has unique options, one valid correct index, an explanation, and an evidence reference.
3. Parse the JavaScript and confirm every queried element exists.
4. Open the rendered page in a real browser and confirm Quiz is the default active section.
5. Test every section control and confirm its label, explanation, and visual update together.
6. Test at least one correct-answer path.
7. Test at least one wrong-answer path and confirm the correct option turns green with ✓ Correct answer.
8. Complete the full questionnaire once and confirm Next question, score, progress, and final-result behavior.
9. Switch away from and back to Quiz; confirm its current state is preserved unless the page was reloaded.
10. Verify keyboard selection, visible focus, input labels, progress semantics, and live feedback.
11. Inspect the host-width layout at approximately 736px and mobile at 320px. For a standalone page, also inspect a conventional desktop viewport.
12. Confirm there is no horizontal page overflow at any tested width.
13. Check for browser errors and warnings.
14. Remove temporary screenshots, traces, and browser artifacts from the product repository.
15. Open the finished quiz for the user. If the environment cannot open a GUI, provide the exact path and say so.

If local authentication is required to inspect the feature, follow the repository's documented agent-auth contract. Never add an authentication bypass for this workflow.

Delivery

Lead with the completed outcome. Mention:

• the topic covered;
• that the teaching sections and questionnaire are on the page;
• any important evidence limitation; and
• that the page was opened and browser-checked.

Then provide the host-appropriate inline directive or a direct path to the standalone HTML. Do not bury the usable artifact behind a long process report.

Failure Modes to Avoid