Docs

Lab Contribution Workflow

How Lab Library proposals move from a GitHub Issue into a reviewed Markdown package.

Purpose

The Lab Library is the canonical home for hands-on activities. Contributors use GitHub Issues for proposals, assignment, and review; Markdown packages in labs/ remain the durable curriculum source.

Package Contract

Every lab has a folder at labs/<lab-slug>/ with a canonical learner-facing lab.md and a required history README.md. The lab.md frontmatter owns the title, summary, Release mode, relationships, level, format, owner, review status, and all learner materials. Its body owns the complete Activity. The README contains only its title, [Return to lab](/websites/rs-ai-learning-lab/docs/lab/), ## Origin story, and a reverse-chronological ## Change log with dated ### YYYY-MM-DD entries.

Use release_mode: alpha for an idea under development, beta for a runnable lab whose required documents are ready, and gold only when every standard material slot is ready with at least one working resource. Keep detailed review state separate from this public readiness label.

Every canonical lab declares these seven keys in one materials map, in any source order: required_documents, lab_notebook, learner_guide, related_articles, videos, gallery, and facilitator_guide. Each slot declares status: ready with one or more items or status: coming_soon with an empty items list. Every ready item requires title and href; it may also declare format, purpose, and used_at_steps. Local paths are relative to the lab package and must resolve inside it. A coming-soon slot is a visible commitment, not a dead or invented link. Gallery is the only public worked-example home; facilitators may select an appropriate model there.

Place ## Lab materials and exactly one <!-- lab-materials --> marker before the Activity introduction and steps. Place ## Learner Map and exactly one <!-- learner-map --> marker after optional extensions and before learner feedback. The renderer expands these markers from lab.md metadata. 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 also appear as compact moment-of-use reminders in the numbered step that needs them.

During the pilot, release_mode in lab.md selects the canonical contract. Unmigrated labs temporarily retain their existing README metadata, legacy routes, and rendering behavior. This fallback keeps the library stable during review; do not use both ownership models in a migrated package.

The Activity source must be usable by a learner without a second editorial rewrite. Keep relationships, Release mode, review, and source-location metadata in lab.md frontmatter and generated provenance records. Renderers may compose the Activity’s approved sections into a different layout, but altered wording or meaning requires a new Activity review or an explicitly fingerprinted presentation-copy review. A separately adapted internal/public source pair remains appropriate for articles or other artifacts whose audiences genuinely require different editorial treatment; it is not the default for routine Activities.

Artifact receipts and final-QC receipts still say what humans reviewed against exact fingerprints. Pilot or field-note evidence records what happened when people used the lab. Freshness and rereview policy will say when previously reviewed material needs another look; that automation is not part of the current POC.

Raw artifact receipts are retained under review-evidence/labs/<lab-slug>/<artifact-id>/, outside the learner-facing labs/ tree. A needs-revision receipt remains evidence for the reviewed fingerprint; it does not approve the changed artifact, which must return for a fresh review.

A Beta may therefore be reviewable while optional companion material remains incomplete. For example, a missing finished video blocks Gold without blocking learner or reviewer use of a runnable Activity whose required documents are ready. Never promote Release mode merely because a separate review state changed.

The Activity owns the numbered learner steps, result check, completion checklist, and optional extensions. A genuine Notebook carries the complete instruction for every numbered step in the same order and with the same title, working resource links, purpose-specific recording fields, and a general-notes area. It presents one step at a time with Back and Next controls and offers Download Markdown and Download JSON. Working resource links open in a new tab, and edited, unexported work receives a leave-page warning; the Notebook does not autosave. A step declares repeatable observations only when its work genuinely requires more than one observation. When declared, the prompt list is non-empty; adding another observation repeats the complete prompt set, moves keyboard focus into the first field of the new record, and announces the observation and step. Steps without declared observation prompts render and export no observation structure. The Notebook also carries the Activity checklists and binds its review to the Activity fingerprint. An interactive has its own review contract for orientation, mechanics, feedback, accessibility, local state and privacy, and the whole artifact; it does not inherit Notebook completion semantics.

Delivery and reviewer context

Support self-study, Zoom, and in-person use unless the activity needs a particular setting. Explain facilitator demonstration followed by learner practice individually, in pairs, or in groups. Watching a demonstration is preparation; completion depends on the learner actions and decisions in the Activity, including when a pair or group shares a question. Synchronize this guidance into the Notebook.

Keep human-readable reviewer briefs in package README pages. Link to one owning brief for shared context. Name intended audiences, delivery modes, artifact roles, current limitations, and deferred work; ask reviewers to record the version and surfaces inspected. A brief does not substitute for missing learner instructions or establish pilot readiness.

A Gallery is ready only when its landing page links at least one actual worked example. Contribution guidance, submission templates, and descriptions of future examples do not count. Every linked example must include an explicit Provenance: statement or provenance_type frontmatter so a learner can distinguish an illustrative model, reconstructed collaboration, learner contribution, and other origins. If no linked example satisfies this contract, keep the Gallery coming_soon with an empty item list.

Video readiness

A video slot is ready only when it links a contextual Markdown or HTML landing page. Do not link the material slot directly to an MP4, MOV, or WebM file. The landing page must embed the player, load an external WebVTT captions track, and link a readable Markdown or text transcript; caption and transcript files must resolve inside the lab package.

Video production must align visual cues with the narration they explain and verify the final timeline directly. Do not use an encoder’s -shortest option as a substitute for matching visual, audio, and caption timing.

For an assigned issue already labeled stage:draft, contributors may use the project-local draft-learning-lab skill to create a complete local Draft package. The skill accelerates drafting only; it does not replace issue triage, human review, pilot work, or the linked pull-request workflow.

Intake and Delegation

  1. A contributor opens a Lab Activity GitHub Issue with learner outcome, proposed module, scope, materials, safety/privacy boundary, take-home artifact, review needs, and acceptance criteria.
  2. Triage checks overlap, confirms the primary module and track, assigns an owner and reviewer, records credit/payment terms where applicable, and moves the issue from Inbox to Ready to Shape or Parked.
  3. The assigned contributor creates or enriches the package in a branch and opens a pull request linked to the issue.
  4. The owner and assigned reviewer verify the learner path, observable output, privacy/safety boundary, accessibility, and package links. Add specialist review only when the lab warrants it.
  5. Move the issue through Drafting, Review, Pilot Prep, Pilot / Field Notes, and Done only when the evidence supports it.

Boundaries

  • GitHub is the work queue. Do not create duplicate Markdown backlog rows for unapproved proposals.
  • Do not mark a package ready merely because its prose is complete. Availability, pilot evidence, accessibility, safety, specialist review, and future freshness gaps remain visible in their own records.
  • The Module to Interactive Single-Page Application is an approved exception for a local static prototype. It does not authorize accounts, APIs, analytics, cloud storage, persistence, or a broader application platform.

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: docs/lab-contribution-workflow.md