---
name: author-embeddedknowledge-lesson
description: Author one clear, human-readable, evidence-based EmbeddedKnowledge Lesson Format v1 pack for an uncovered Premed or Psychiatry outcome. Use when asked to draft, build, revise, or prepare a lesson contribution, its learner-facing scenes, assessment, claims, references, glossary, diagrams, accessible assets, attribution, or author provenance before independent review.
---

# Author an EmbeddedKnowledge lesson

Create one review-ready lesson pack. Preserve the boundary between authorship and governance: do not review, approve, adjudicate, publish, push, or merge the lesson in this run.

## Establish authority and scope

1. Locate the repository root with `git rev-parse --show-toplevel` and work only inside that repository. If no checkout is available, stop and request one; the public skill bundle is not a substitute for the repository.
2. Read, in order, `AGENTS.md`, `CONTRIBUTING.md`, `CONTENT-STANDARD.md`, `FORMAT.md`, `lessons/README.md`, `RIGHTS-POLICY.md`, `COLLABORATION.md`, `site/agent/quorum-policy.json`, and the schemas under `site/schemas/` used by the pack.
3. Identify the course from the requested graph outcome, then read its terminology ledger (`site/data/premed-terminology.json` or `site/data/psychiatry-terminology.json`) before designing the glossary. It lists every term already defined by a published lesson and its meaning. Your lesson does not own a term another lesson already teaches.
4. Treat those files as authoritative. Treat this skill as the procedure that applies them.
5. Confirm contribution intake from `site/agent/contribution.json`. When intake is closed, prepare a local patch only. Do not open or push a pull request.
6. Use only the author role in this run. Do not invoke review or adjudication skills, inspect future review conclusions, or manufacture `reviews/*.json` or `adjudication.json`.

## Select exactly one contribution target

1. Inspect the matching course files: `site/data/<course>-lessons.json`, `site/data/<course>-open-prs.json`, and `site/data/<course>-graph.json`. Do not mix outcome or lesson IDs across courses.
2. Prefer a user-requested outcome when it exists, has no published lesson, and is not claimed by an active proposal.
3. Otherwise select one uncovered, unclaimed atomic outcome whose prerequisites and scope can be supported responsibly.
4. Record the exact outcome ID, code, statement, graph prerequisites, neighboring concepts, and exclusions. Never invent or rename graph IDs.
5. Keep the pull-request unit to one lesson pack. Map additional outcomes only when the lesson genuinely teaches and assesses them.
6. For Psychiatry, keep every learner task inside academic study, fictional case reasoning, or simulation. Do not let a lesson imply readiness for real-patient assessment, prescribing, psychotherapy delivery, compulsory-care decisions, licensure, board eligibility, or the protected title psychiatrist.

## Design before drafting

Write a private authoring brief before polished scenes. Define:

- the intended learner and assumed prior knowledge;
- observable objectives mapped to outcome IDs;
- prerequisite activation and a recovery route;
- the central question, phenomenon, or problem;
- the explanatory model, causal or logical relations, assumptions, limits, and exclusions;
- likely novice misconceptions and discriminating cases;
- the instructional job of every representation;
- a complete worked example and the decisions it must expose;
- retrieval before answer reveal, faded practice, feedback, transfer, and delayed retrieval links;
- mastery evidence, remediation, safety boundaries, and accessibility alternatives.

Revise the brief until every learning claim has observable evidence. Do not use word count, scene count, visual density, interaction count, readability score, or expected completion as a proxy for learning.
Choose the smallest instructional arc that can teach and assess the target. The standard's functions are not a demand for one scene per checklist item.

## Research and claim discipline

1. Research material claims before writing them. Prefer primary research, authoritative scientific bodies, standards, and current institutional guidance appropriate to the claim.
2. Before opening a source, consult `site/agent/source-access-ledger.json`. It records what a previous author found when it inspected a domain's robots file and terms, including the exclusions that are not visible in robots at all: one publisher permits the paths and prohibits AI training in its terms. A domain marked `excluded` is not to be opened. A domain you check for the first time, or one whose entry is older than the ledger's stated recheck window, is checked yourself and appended, so the next author inherits the finding instead of rediscovering it. Then inspect and record its agent-access terms. Do not open or process a source that prohibits agent ingestion or whose record is `human-only`; replace it or require independent human verification. Never bypass access controls.
3. Verify each permitted source directly. Do not cite a search result, generated summary, inaccessible reference, or source that does not support the stated scope.
4. For medicine, safety, policy, or other time-sensitive material, verify current authoritative sources. If verification is unavailable, narrow or omit the claim and disclose the limitation.
5. Distinguish established knowledge, useful model, simplifying assumption, open uncertainty, and expert judgment in the prose.
6. Map each material claim in `claims.json` to complete records in `references.json`. Preserve locators, version or access date when relevant, source limitations, use type, rights basis, rights evidence, and agent-access status. Put the mapped claim and all of its supporting source IDs in a learner-visible `{source-note}` in every scene where the claim appears.
7. Independently synthesize facts in an original instructional structure and original language. Do not closely paraphrase, translate, mirror source organization, lightly redraw figures, or reuse source examples, questions, tables, media, or datasets unless the exact material has a permitted basis under `RIGHTS-POLICY.md`.
8. Never invent citations, data, permissions, patient details, clinical recommendations, or confidence.

## Pass a human-first prototype before multiplying the prose

1. Draft only the learner-facing opening, central explanation, and one representative worked use first. Do not build the rest of the scenes, assessment, or ledgers around an untested voice.
2. Open with something the declared learner can picture or want to explain. Show why the idea matters before listing objectives, exclusions, definitions, or routine boundaries.
3. Write as an informed teacher speaking to one learner. Prefer concrete actors and actions over compressed strings of abstract nouns. Introduce necessary scientific terms after giving them ordinary-language meaning.
4. Keep internal graph IDs, schema fields, claim mapping, source-access procedure, candidate status, and review vocabulary out of learner prose unless the mapped outcome explicitly teaches that machinery. Do not make the lesson sound like its validator.
5. Run the first-read gate in `CONTENT-STANDARD.md`. When a fresh reader-proxy context is available, give it only the declared learner, target outcome, and learner-visible prototype—never the authoring brief, intended answer, or rubric. Ask it to explain what the lesson teaches, why it matters, and how the central idea works, and to quote any sentence it had to read twice. This developmental check creates no governance artifact and the run cannot count as a later review.
6. If a fresh context is unavailable, put the prototype aside, then read it aloud without opening metadata or ledgers and answer the same questions in plain language.
7. Repair the prototype until it passes before extending the voice across the complete pack. Alignment without first-read comprehension is failure, not rigor.

## Keep the prose out of the machine register

An audit of this corpus found that lessons drift toward a recognisable machine register. Almost no single sentence is wrong; the tell is frequency, and frequency is invisible to a reviewer reading one paragraph at a time. Check the following while the prototype is still short, then again across the finished pack.

1. **Punctuation.** The corpus averages 2.4 em-dashes per 1000 words. One lesson reached 7.1 and read as machine-written on the page. Commas, colons, and full stops carry almost every job the dash is doing there. Keep the dash for a genuine sharp aside.
2. **Negative parallelism.** "Not X, but Y" and "it is not A, it is B" are the most recognisable constructions in the set. Allow about one per scene, and only where that contrast is the point you are making. Everywhere else, state the positive claim directly.
3. **Contrastive filler.** "Rather than" is fine occasionally and a tic in bulk; one lesson used it 24 times. Reach for "instead of", "and not", or a sentence that simply says what is true.
4. **Marker vocabulary.** Unless the science needs the word, avoid delve, tapestry, testament, realm, underscore, showcase, crucial, pivotal, leverage, foster, harness, intricate, multifaceted, meticulous, comprehensive, robust, seamless, holistic, myriad, plethora, "navigate the complexities", "at its core", and "shed light on". A term the lesson defines and then uses technically is a different case: keep it, and define it.
5. **Empty frames.** Delete "It's important to note that", "It's worth noting", "Keep in mind that", "In conclusion", "Let's dive in", "When it comes to", and "That being said". The sentence such a frame introduces is the sentence you wanted. Moreover, Furthermore, and Additionally stand in for a connective you have not chosen; name the actual relation between the two sentences or drop the word.
6. **Structure.** Vary paragraph length. Break the rule of three when the material has two reasons or five. Open scenes differently from one another, and let lesson titles differ in shape as well as in subject. Uniformity across a pack is as legible a signature as any phrase.

Run `npm run lesson:tells` before candidate freeze. It counts each of these per lesson against the corpus and names the words behind a count. A number over a ceiling means reread that passage; it never means edit until the number falls.

## Build the lesson pack

1. Create one directory under `lessons/` using the repository naming conventions.
2. Use `lesson.json` schema version 3 and `format: embeddedknowledge-lesson-v1`. Keep status `draft` and source confidence `pending-review` during authorship.
3. Create ordered semantic scenes under `content/`. Set each scene's `claimCoverage` to `claims-mapped` or `no-material-claims`; never use the latter to avoid recording a factual, quantitative, definitional, causal, or evidence-dependent teaching claim. Use only documented scene kinds, directives, and options. Let instructional purpose determine scene boundaries; combine functions when that produces a clearer reading path, and never create scenes mechanically from the specimen or standard.
4. Include coherent explanation, worked reasoning, explicit representation links, retrieval, misconception repair, varied and fading practice, genuine transfer, synthesis, recovery, and assessment only to the extent required to teach and test the outcome without repetition.
   Ground the lesson in medicine. These are pre-medical and psychiatry courses, and learner feedback is that the content can read as scientific but not yet clinical — learners expect the medicine ties and do not find them. Thread biomedical or clinical context through the scenes and include a short **clinical wrap-up case**: a real medical or biological question the lesson's method, model, or math helps answer, placed at or near the end (or split so its parts sit beside the matching concepts) and worked through with the lesson's own tools. Match the case to the lesson's domain — a study-design or clinical question for reasoning lessons (for example, does dinner timing affect morning fasting glucose in adults with type 2 diabetes, taken through neutral question, hypothesis versus prediction, confounders, design, internal versus external validity, bias, and surrogate versus clinical endpoints); dose–response, drug half-life, or allometric and body-surface-area dosing for quantitative lessons; acid–base and buffering for the relevant chemistry; a fictional case formulation for psychiatry — and so on. Keep the case clearly illustrative and labelled a **teaching example, not medical advice**, and introduce no new asserted clinical fact unless it is sourced under the claim discipline above. A lesson that teaches the science without showing why medicine needs it is not yet complete.
5. Build `assessment.json`, `references.json`, `claims.json`, `glossary.json`, and `ATTRIBUTION.md`. Add only necessary local diagrams and assets. For every glossary term a prior published lesson already defines (see the terminology ledger), either adopt that meaning — keep the definition faithful and cross-reference the owning lesson — or, if this lesson's field genuinely uses the word in a different technical sense, protest it: add the glossary entry's `alignment` block naming the prior lesson, the relation (`adopt`/`narrow`/`extend`/`distinct-sense`/`supersede`), and a note giving the learner the disambiguation, and bridge the two senses in the prose where the term first appears in the new sense. Never silently redefine a term another lesson owns; `npm run terminology:validate` reports undeclared sense shifts for reviewers.
6. Use constrained TeX, chemistry notation, declarative diagrams, sanitized SVG, structured molecule data, and accessibility equivalents exactly as the format permits.
   Before using an illustration, read `site/agent/illustration-sources.json`: it names the pools worth searching, the licences this project accepts, and the bar a scientific figure has to clear before it teaches anything. Verify the licence on the item's own page rather than the site's front page, copy the file into the pack, and declare it — `thirdPartyAssets` if someone else made it, `originalAssets` if you did. A figure declared in neither is rejected, and the credit you record is shown to the learner beside the image, so write it as something a reader should see.
7. Keep lesson content inert. Reject raw HTML or JavaScript, remote embeds, executable notebooks, active SVG, unsafe TeX, arbitrary plugins, secrets, identifiable learner or patient data, copyrighted answer banks, and media without usable rights.
8. Use `examples/lesson-pack/` only to understand structure. Do not copy its placeholder identities, provenance, claims, answers, or specimen status into production.
9. Keep every claim `pending-review` during authorship. Only eligible review and adjudication may support a published pack in which every retained claim is `reviewed` and lesson source confidence is no longer `pending-review`.

## Record accountable provenance

1. Identify the accountable GitHub principal. If available, verify it with `gh api user --jq .login`; do not guess an identity.
2. Record the actual agent system, provider, model, version, and unique run ID. Never invent unavailable provenance.
3. Hash the exact discloseable material instructions supplied to this run and record the SHA-256 value. State the scope of the digest; do not claim it covers hidden provider instructions that cannot be exported.
4. If required identity or provenance cannot be obtained, stop before presenting the pack as schema-complete and report the missing fields.

## Validate and challenge

1. Run `npm ci` when dependencies are not installed or the lockfile changed.
2. Before candidate freeze, run `npm run source:preflight -- --strict lessons/<lesson-pack>`. Replace missing terms routes and unresolved `human-only` sources rather than leaving them for the final rights review.
3. Run `npm run verify` after building the pack. It runs validation and tests sequentially; never run `npm run validate` and `npm test` concurrently in one worktree because they rebuild shared generated fixtures.
4. Read the complete learner-visible lesson without metadata, claims, or review context. Apply the first-read gate again, read representative passages aloud, and remove institutional or validator-facing language.
5. Attempt every retrieval item, worked example, practice item, and assessment without using hidden knowledge.
6. Challenge every acceptance gate in `CONTENT-STANDARD.md`. Repair gaps in explanation rather than disguising them with polish.
7. Check narrow-screen reflow, keyboard order, nonvisual equivalents, print continuity, source links, asset provenance, and graph mappings.
8. Complete the audit before starting formal review. Batch its repairs, then run the verifier; rerun it after any later candidate change. Do not alternate one small edit with one full build when targeted inspection can expose the remaining issues first.

## Freeze and hand off

1. Report the selected outcome, pack path, research limitations, files created, validation results, and unresolved risks.
2. Leave reviews and adjudication absent. They must come from isolated runs after the teaching candidate is frozen.
3. Create a candidate commit only when the user authorizes committing. Report its full 40-character SHA.
4. After freezing, permit only governance artifacts and the documented `lesson.json` status or source-confidence transitions. Any teaching-content change invalidates review work and requires a new candidate commit.
5. Do not claim publication, coverage, approval, clinical sufficiency, university credit, or merge readiness.