Contributing Guide

Thanks for your interest in contributing! This repo grows better with community input — whether that's fixing a typo, improving an answer, or adding new questions.

Ways to Contribute

How to Submit

  1. Fork the repository
  2. Create a branch — git checkout -b add-modular-rag-q6
  3. Make your changes following the format below
  4. Open a Pull Request with a short description of what you changed and why

Question Format

Each question should follow this structure:

## Q6. Your question here? `[Basic|Intermediate|Advanced]` `[Scenario]`

<details>
<summary>💡 Show Answer</summary>

**Answer:**

Your answer here. Use tables, code blocks, and bullet points where they aid clarity.

</details>

A multiple-choice question adds a lettered option list between the heading and <details>, and the first line of the answer names the correct option:

## Q23. Which metric rewards ranking the first relevant chunk high? `[Intermediate]` `[MCQ]`

- A. Precision@k
- B. Recall@k
- C. MRR
- D. Faithfulness

<details>
<summary>💡 Show Answer</summary>

**Answer:**

**Correct: C.** MRR averages 1/rank of the first relevant hit, so it specifically
rewards surfacing the first good answer earlier — unlike precision or recall,
which ignore ordering, or faithfulness, which measures something unrelated.

</details>

Every question needs exactly one difficulty tag. The [Scenario] and [MCQ] tags are each optional and additive — put the difficulty tag first, then [Scenario] and/or [MCQ] if they apply (all three can combine, e.g. `[Advanced]` `[Scenario]` `[MCQ]`).

Difficulty guidelines:

The [Scenario] tag:

Add [Scenario] (alongside a difficulty tag) when the question drops the candidate into a concrete situation — a named domain, corpus, SLO, incident, or constraint — and asks them to design, diagnose, decide, or trade off, e.g. ## Q19. Design a Naive RAG system for an internal HR/policy chatbot. [Advanced] [Scenario]``. Difficulty still describes how much expertise the answer needs — a scenario question can be [Basic] if a beginner-level design is all that's asked for. Don't tag a purely conceptual "what is X" or "compare X and Y" question, even if its answer happens to mention a real-world example in passing. The practice quiz's "Scenario only" filter lets candidates drill just these questions.

The [MCQ] tag:

Add [MCQ] when the question has a single defensible correct answer among a small set of options — a good fit for metrics, hyperparameter choices, "which of these is true" style facts, or a scenario with one clearly-best option. The practice quiz auto-grades these: the candidate clicks an option and sees immediately whether they were right, instead of self-reporting "Got it" / "Review again". The self-assessment page (assessment.html) also draws its exam sets only from [MCQ] questions, so every new MCQ widens that pool.

Format rules, enforced by npm run check:

Authoring guidance: write distractors that are plausible mistakes, not random noise — a knowledgeable candidate should have to actually reason about the difference. The explanation should say why the correct option is right and briefly why each distractor is wrong, which naturally clears the same 40-word minimum every answer needs. [MCQ] composes with difficulty and [Scenario] as above.

Style Guidelines

Validating Your Changes

Before opening a PR, run:

npm test                # runs the parser's unit tests
npm run check           # validates format, numbering, tags, duplicates
npm run gaps -- --file 13   # (optional) shows per-file progress toward the 22-question target
npm run readme          # regenerates the README's per-file counts, totals, and badge
npm run build           # builds the site into _site/ and confirms your questions render

npm run check will fail the build if a question is missing its difficulty tag, has more than one difficulty tag, uses an unrecognized tag, is numbered out of sequence, is missing the <details>/**Answer:** structure, or duplicates another question's title elsewhere in the bank. For [MCQ] questions it also checks the option list and the **Correct: X.** key line (E-MCQ-OPTS for a missing/malformed option list, E-MCQ-KEY for a missing/invalid correct-answer line). npm run readme rewrites the questions-### badge and the per-file/section/grand/scenario/MCQ totals in README.md for you — never hand-edit those counts.

Releasing

Maintainer-only steps for cutting a new version:

  1. git pull --ff-only on main, then run npm run ci and confirm it's green.
  2. Bump version in package.json and add a dated entry to CHANGELOG.md. Open a release/vX.Y.Z PR with just those two changes and merge it.
  3. Tag the merge commit and push the tag: git tag -a vX.Y.Z -m "vX.Y.Z — <one-line summary>" then git push origin vX.Y.Z.
  4. Create the GitHub Release from that tag, using the matching CHANGELOG.md section as the release notes: gh release create vX.Y.Z --title "..." --notes-file <path>.
  5. Versioning: major for restructures or anything that breaks existing links, minor for new sections or tooling, patch for fixes and wording. Pushing to main already redeploys the site — the tag/release is a version marker, not a publish step.

Opening Issues

Use issues to: