RS AI Learning Lab contributor template — working v1

This template was derived from the first five labs. Complete Tier 1 for every proposed activity. Use Tier 2 only when the activity actually needs it; do not pad a simple lab with irrelevant operational detail. Keep the template under review as more kinds of activities are built.

Tier 1 — required for every lab

Explain how to use the activity for self-study, Zoom, and in-person sessions where applicable. Facilitated sessions begin with an example, then learner practice individually, in pairs, or in groups. Watching the example alone is preparation; state the learner decisions and actions needed for completion. Learners may adopt a shared question. Keep reviewer context in the package README and essential participation guidance in the Activity and synchronized Notebook.

Identity and placement

Record these fields in the package lab.md frontmatter. lab.md owns all learner-facing metadata, materials, relationships, and Activity content. Do not make the learner read administrative placement or review metadata before beginning the Activity.

• Title:
• Summary:
• Primary module, related modules, and related tracks: Use source slugs so the renderer can build the Learner Map.
• Release mode: alpha, beta, or gold. Use alpha for an idea under development, beta for a runnable lab whose required documents are ready and whose companion materials may still be coming soon, and gold only when every standard material slot is ready with at least one working resource.
• Review status: Name the outstanding human review without treating prose completion as pilot evidence.
• Materials: Declare all seven slots in the materials map: required_documents, lab_notebook, learner_guide, related_articles, videos, gallery, and facilitator_guide. Each slot has status: ready with one or more items, or status: coming_soon with an empty items list. Every ready item has title and href; format, purpose, and used_at_steps are optional. Local paths are lab-package-relative. Gallery is the only public home for worked examples.
• Pilot evidence: Record pilot or field-note evidence separately when it exists.
• Freshness: Leave rereview dates and triggers unset during the POC; do not treat missing automation as proof that content remains current.
• Level, format, and owner: Keep these concise and learner-readable where rendered.

Keep the required package README.md to four parts: its title, [Return to lab](/websites/rs-ai-learning-lab/ops/templates/lab/), ## Origin story, and ## Change log. Use dated ### YYYY-MM-DD change entries in reverse chronological order. Do not duplicate metadata, materials, relationships, Activity instructions, or review controls there.

During the canonical-page pilot, release_mode in lab.md identifies a migrated lab. Unmigrated labs temporarily retain the legacy README metadata and rendering contract; do not mix that fallback with the canonical contract in a migrated package.

Learner case

• Purpose: What will the learner explore, and why does it matter?
• Observable outcomes: Use verbs such as compare, identify, revise, explain, create, or decide. Avoid “understand.”
• Requirements: tools, source material, account limits, and any privacy boundary.
• Key idea and vocabulary: define terms at first use; name misconceptions the activity addresses.

Learner path

Write lab.md as the complete learner-readable Activity, not as notes for a later adaptation. A learner should encounter the goal, preparation, core idea, steps, validation, completion criteria, optional extensions, and only then any deeper supporting explanation. A renderer may change presentation, but it must not silently rewrite approved meaning, instructions, safety guidance, or sequence.

• Setup and learner choices: the starting scenario, content, or question.
• Lab materials: place ## Lab materials and exactly one <!-- lab-materials --> marker near the top of lab.md, before the Activity introduction and numbered steps. The renderer inserts all seven declared material slots there in fixed group and slot order. The required_documents category displays as Documents. Each document may declare a boolean required (default true); use required: false for an optional document. Items display Required or Optional. Documents may retain compact moment-of-use reminders inside the Activity.
• Notebook orientation: use this visible sentence before the numbered steps: “Complete the activity here. Open the optional [Lab Notebook] beside this page when you want a place to record your work.” Link Lab Notebook to the declared Notebook resource.
• Notebook step contract: present one numbered Activity step at a time with Back and Next controls. Keep the same order and title, and include the complete instruction, working resource links, purpose-specific recording fields, and general notes. Offer Download Markdown and Download JSON; open working resource links in a new tab and warn before leaving with edited, unexported work. Do not add autosave without changing the stated local-state and privacy contract. Declare a non-empty repeatable observation prompt set only when that step genuinely requires more than one observation; otherwise render and export no observation structure. When an observation has multiple prompts, repeat the complete record for every added observation; do not compress one-to-many observations into a single shared template response. After a learner adds an observation, move keyboard focus to its first field and announce which observation was added to which step.
• Numbered activity steps: place the primary ordered list immediately after the Activity introduction so the website renders each step as a numbered callout. Include a try → observe → change → compare → reflect loop.
• Prompt guidance (if used): say what each example prompt is for, what the learner may adapt, and what must remain fixed for a fair comparison. Do not present a magical prompt.
• Observation guide: specific things to notice.
• Validation and limits: what can be checked, what needs outside evidence, what needs human review, and what cannot be established here.
• Reflection and completion criteria: testable definition of done.
• Learner Map: after optional extensions and before learner feedback, add ## Learner Map followed by exactly one <!-- learner-map --> marker. The renderer builds the map from the relationship metadata; do not maintain a second hand-written relationship list.

Sharing responsibly

• Gallery artifact: what to save, process evidence, preferred format, suggested caption, and what makes it educational.
• Accessibility: plain language, readable structure, non-color cues, alternatives for audio/visual material, keyboard or pacing needs.
• Safety, privacy, and ethics: confidential material, consent, copyright, sensitive claims, and tool-data boundaries.

Tier 2 — required when applicable

Use only relevant sections.

• Facilitator plan: timing, preparation, common difficulties, discussion prompts, productive failure, and adaptations.
• Group roles: if the activity needs a recorder, observer, presenter, or reviewer.
• Worked example: source input, first result, observation, revision, new result, comparison, reflection, and validation note. Label illustrative examples honestly.
• Transformation safeguards: preservation risks, claim/source review, redaction process, and what a human may need to restore.
• Technical or app brief: learning objective, primary interaction, minimum viable version, data handled, local/cloud behavior, deployment, accessibility, test checklist, and launch instructions.
• External material or dataset: permissions, provenance, copyright, translation review, consent, or human-subject concerns.
• Assessment or printable material: rubric, answer limits, print layout, or facilitator handout.

Tier 3 — optional enrichment

• short / extended version
• alternative scenarios or community/workplace adaptations
• vocabulary sheet or discussion guide
• advanced extension or capstone link
• audio/video transcript and caption plan
• facilitator mode, sample completed activity, or reusable data format

Contributor self-check

• lab.md owns the complete canonical metadata, all seven material slots, relationships, and learner-readable Activity.
• Release mode honestly distinguishes an Alpha idea, a runnable Beta, and a complete Gold lab.
• Every material slot is explicitly ready with working items or coming_soon with no items; a missing artifact is visible rather than hidden by review status.
• Gallery is the only public worked-example home.
• README.md contains only its title, Return to lab link, Origin story, and reverse-chronological Change log.
• A learner can complete the activity without oral explanation.
• The Activity uses the approved optional Lab Notebook sentence before the numbered steps.
• ## Lab materials and ## Learner Map contain their single canonical rendering markers at the approved locations.
• Required documents retain direct moment-of-use reminders at the steps where learners need them.
• The Notebook presents every numbered Activity step one at a time with its complete instruction, resources, recording fields, and notes; repeatable observations appear only in steps that genuinely need them; Markdown and JSON exports are available; resource links open separately; and edited, unexported work receives a leave-page warning without autosave.
• The visible output and revision loop are clear.
• The worked example includes an imperfect first result or unresolved limit.
• Claims about tools are bounded and current-tool details are not embedded in durable teaching prose.
• Gallery evidence shows process, not only polish.
• Privacy, consent, accessibility, and human-review limits are specific to this activity.

Keep learning completion estimates only in facilitator guides or facilitator notes, marked provisional and refined with observed participation. Do not add duration metadata or completion estimates to learner pages, catalogs, worksheets, walkthroughs, or notebooks. Preserve timings that define an exercise or media artifact, such as a 45-second speech.

---

Source: templates/lab-contributor-template.md