# Recipes

Short answers, for when you know the shape of the tool and want the invocation.

## Assembly

**Draw only from material I have taught.**
`--lectures l09,l10,l11`.
Combine with `--topics` and `--banks` to narrow further; the filters intersect.

**See the draw before committing to it.**
`--dry-run`.
Prints the selection and any notes about constraints that had to bend, and writes nothing.

**Reproduce a draw exactly.**
`--seed N`.
The same seed against the same pool gives the same items in the same order.
Recorded in the assessment file, so a draw stays reproducible after the fact.

**Two forms that differ only in option order.**
`--forms 2`.
Each form gets its own seed; item order is shared unless the form sets `shuffle_items`.

**A blueprint I cannot satisfy.**
The error names the level, how many items were asked for, and how many were available after filtering.
Usually the fix is a shorter cooldown or a wider lecture range, not more items.

## Reuse

```console
$ coursebank usage history q-align-recall-001
$ coursebank usage unused
```

`unused` lists approved items never placed on an assessment, which is the queue of work you already did and forgot about.

## Exports

**A printable exam.**
`coursebank export typst exam-2 --form all`.
Add `--variant key` to write only the key.

**A Canvas quiz.**
`coursebank export qti exam-2 --form A`.
Add `--no-feedback` to leave per-option feedback out of the package.

**A Markdown copy for a colleague to read.**
`coursebank export md exam-2`.
Add `--with-key` for the answers and rationales.

**Restyle the printed output.**
`coursebank template dump`, then edit `templates/exam.typ`.
See [`typst_export`](crate::guide::typst_export).

## Ingest

**Gradescope.**
`coursebank ingest gradescope grading/exam-2/ --assessment exam-2`.
Point it at the directory holding the per-question CSVs.

**Canvas.**
`coursebank ingest canvas export.csv --assessment exam-2`.
The Student Analysis export, not the gradebook.

**Keep student identities out of the repository.**
`--pseudonymize --salt-file ~/.coursebank-salt`.
Keep the salt outside the repository; the point of the salt is that hashed ids cannot be brute-forced over a class roster, which fails if the salt sits next to them.

**Check a parse before writing.** `--dry-run`.

## Analysis

| Question | Command |
|:--|:--|
| Which items misbehaved? | `analyze items --assessment exam-2` |
| How hard is each item, on a common scale? | `analyze irt --assessment exam-2 --model 2pl` |
| Which students are struggling, and with what? | `analyze students --assessment exam-2` |
| What is in the store? | `data` |

Pool across terms by passing the assessment id rather than one administration id.
Twenty-four students supports very little; ninety-six across four terms supports something.

## Reports

```console
$ coursebank report students --assessment exam-2
$ coursebank report cohort --assessment exam-2
```

The student report omits correct answers, other students' data, and any rank.
Hand it out without a second pass.

## After grading

**An option turned out to be defensible.**
Add `credit_overrides: {C: 0.5}` to the placement in the assessment record.
Do not edit scores by hand, or item analysis sees different numbers than the students did.

**An item was broken.**
Add `dropped: true` to the placement.
It leaves the scored matrix and is not printed on re-export, but the record of having asked it stays.

**Statistics onto the items.**
`coursebank calibrate --assessment exam-2`, read the diff, then `--apply`.

## Housekeeping

**Editor validation stopped working.**
`coursebank schema` rewrites the JSON Schemas.
They ship with the binary, so an upgrade can leave them stale.

**A pre-commit hook.**
`coursebank validate && coursebank lint`.
Exit code `2` means findings, `1` means the command failed, so a hook can treat them differently.

**Build without Parquet.**
`pixi run build-lean`.
The response store falls back to CSV.
Useful if you want a binary with a shorter dependency list; the tradeoff is slower reads on large stores.