Overview
Use this skill to author regular bptools-based Python generators in biology-problems.
Follow the repo's shared generator patterns and verify output with small local runs.
Required reading (load before any bptools edit)
skills/bptools-writer-expert/references/docs/QUESTION_AUTHORING_GUIDE.md- Primary authoring workflow, TEMPLATE.py conventions, required structure.
bptools.pyat the target repo root (this skill is only invoked insidebiology-problems, so the file is reachable at the repo-root path returned bygit rev-parse --show-toplevel).- Canonical helper API. Copying signatures from memory drifts fast; read the
live file so
formatBB_*,collect_and_write_questions,make_outfile, and anti-cheat flags match what is actually defined.
- Canonical helper API. Copying signatures from memory drifts fast; read the
live file so
Do not summarize from memory. Exception: if you already Read both in this session, say so and continue.
Domain-specific guides in references/docs/problems/ must be loaded when the
task touches that domain (matching sets, PUBCHEM, MC statements, pedigrees,
phylogenetic trees). See references/docs.md for the full index.
Workflow
-
Classify the request and detect project state
- Use
references/topic_index.mdas the routing front door: match the request to a row and load the named guide before opening any generator file. - Use
references/task_selection.mdto classify question family, output format, randomization scope, and anti-cheat policy before writing any code. - Use
references/project_workflow.mdto detect whether the target repo is greenfield (no generator exists for this question type) or existing (generators already present). Greenfield: start from TEMPLATE.py, write the authoring contract, implement with bptools primitives, validate with a small run, prove reproducibility. Existing repo: inspect-first (read live bptools.py, inventory generators), identify the current design, make one generator change at a time, then collect the three proof artifacts (before/after sample, seed log, anti-cheat audit).
- Use
-
Satisfy the Required reading block above. This is step zero.
-
Identify scope
- Confirm the target script(s), question type(s), and output format(s).
- Read
references/repos.mdto locate the target repo path. - Read
references/docs.mdfor any additional guides relevant to the task.
-
Start from known patterns
- Reuse the nearest template in
references/templates.md. - Keep a script structure with
parse_arguments(),write_question(), andmain(). - Use shared parser helpers from
bptoolsfor consistent CLI flags.
- Reuse the nearest template in
-
Implement with bptools primitives
- Build prompts/choices as plain strings and lists.
- Format questions with the relevant
bptools.formatBB_*function. - Use
bptools.collect_and_write_questions(...)andbptools.make_outfile(...). - Respect anti-cheat defaults and only override intentionally.
-
Validate behavior
- Run the modified generator with a small count (for example
-d 1). - Check produced BBQ text for formatting and expected answer keys.
- Run relevant tests for edited code paths.
- Run the modified generator with a small count (for example
-
Finish cleanly
- Update
docs/CHANGELOG.mddirectly when this skill runs as a standalone task; underdelegate-manager-to-subagents, dispatch a docs subagent to add the entry. - Keep generated artifacts out of git (
bbq-*.txt,qti*.zip,selftest-*.html).
- Update
Core rules
- Treat
references/docs/QUESTION_AUTHORING_GUIDE.mdas the primary authoring reference. - Maintain Python style required by this repo: tabs for indentation, ASCII comments,
main()entrypoint. - Keep randomness well mixed for student-facing content; avoid predictable round-robin selection unless explicitly requested for reproducibility/debugging.
- Keep Blackboard sanitizer compatibility patterns (split comments in JS function declarations) when present in existing generators.
- If output behavior is unclear, inspect both
bptools.pyand the correspondingqti_package_makerwriter/validator paths before changing format logic.
Reference files
- Read
references/topic_index.mdas the routing front door: match the request to a row, load the named guide. - Read
references/task_selection.mdto classify question family, output format, randomization scope, and anti-cheat policy. - Read
references/project_workflow.mdfor greenfield and existing-repo workflows on a target biology-problems repo. - Read
references/testing_and_oracles.mdfor fixture corpus, oracles, invariants, and the three required proof artifacts. - Read
references/docs.mdfor the full bundled doc index plus external qti_package_maker pointers. - Read
references/repos.mdfor local repo paths and high-value files. - Read
references/api_surface.mdfor common bptools and qti_package_maker touchpoints. - Read
references/templates.mdfor starter template locations.
Notes
- Bundled docs under
references/docs/are snapshots frombiology-problems/. They can drift from the live repo; treat the live repo as authoritative when they disagree, and refresh the snapshot when the drift matters. - Prefer minimal, targeted changes over broad refactors.
- Reuse existing helper utilities instead of copying formatting logic into each script.
- When the request includes new question families (matching sets, MC statements, pedigrees, phylogenetic trees, PubChem), load the matching optional guide before editing.
Delegated execution
Under delegate-manager-to-subagents, this skill is assigned to a fresh subagent
with one bounded task, the relevant repo rules, and one verification step.
Do not continue the same subagent across unrelated follow-up work; dispatch a
new subagent for each atomic task. See
docs/REPO_STYLE.md.