How to Use the Lab

This page is the operating manual. The README covers one-time installation; this page covers the daily loop.

The daily loop (local application)

  1. Launch: practice-lab start (or the Desktop shortcut created by scripts/make_shortcut.ps1). The dashboard opens in your browser at a 127.0.0.1 address — due reviews, in-progress work, weak areas, and every practice as a card.
  2. Pick: click a due card (or Random), press Start / Re-practice. A fresh attempt folder is created — earlier attempts are never touched — and the working file opens in VS Code at the first TODO.
  3. Work in the attempt file; the canonical prompt with collapsed hints and solution is right next to it.
  4. Finish session: back in the dashboard, record rating (again/hard/good/easy), independence, hints used, confidence, time, the main mistake and lesson. The review schedule and dashboard update immediately.
  5. Add questions with the + Add question button — Quick Add needs only a title, the problem text, topics, and languages; the Advanced section takes starter code, official solutions, tests, and attachments. No terminal, no manual _quarto.yml editing.

The same loop from the terminal (still supported)

  1. Pick a practice:

    python tools/review.py due       # what's scheduled for today
python tools/review.py random    # or surprise me

  2. Open the practice page in Positron (or VS Code with the Quarto extension): practices/<id>-<slug>/python.qmd or r.qmd. Read the problem statement, learning objectives, and the before-coding checklist.

  3. Work in the “My attempt” section. The attempt cells are ordinary executable Quarto cells — put your cursor in a cell and press Ctrl+Shift+Enter (Windows) / Cmd+Shift+Enter (Mac) to run it. Nothing in the attempt section is graded or overwritten.

  4. Stuck? Open Hint 1. Still stuck? Hint 2. The hints escalate from a nudge to a near-spoiler. Only then open the complete solution and its explanation.

  5. Check yourself with the review questions at the bottom — answers are collapsed, so answer out loud (or on paper) first.

  6. Record the session:

    python tools/review.py complete <id> --rating good

    Ratings: again (couldn’t do it), hard, good, easy. The Review Queue page documents exactly how each rating schedules the next review.

Creating a new practice

python tools/new_practice.py --title "Train-validation-test split" `
  --topics machine-learning,validation --languages python,r --difficulty 2

The generator assigns the next sequential id, creates the folder from the templates, validates the metadata, rebuilds the dashboard data, and prints exactly which files to edit next. New practices appear in the site navigation automatically - no configuration files to edit.

Write the official solution as a plain script in the practice’s solutions/ folder and give it a test in tests/ — the check suite then proves forever that your solution still runs.

Running official solutions

Solutions are plain scripts, not notebook state — run them from the repository root:

python practices/<id>-<slug>/solutions/solution.py
Rscript practices/<id>-<slug>/solutions/solution.R

Previewing the site

scripts/preview.ps1        # rebuilds dashboard data, then quarto preview

Quarto watches for changes and reloads the browser. Full-text search (the magnifying glass in the navbar) works in the preview and on any published copy.

Keeping your records private

Everything already stays on your machine unless you publish it. If you do publish your copy (GitHub Pages), two extra options:

  • keep personal notes out of the ## Personal reflection sections, or
  • add progress/progress.yml to .gitignore — the review CLI works identically; your review history simply never leaves your computer.