# 🐍 Lumabit Snake Lesson Generation Specification

## 🎯 Purpose
Generate JSON lessons for each **snake species** in the Southern African snake roadmap, following the Lumabit learning schema. Each lesson must help learners **recognise**, **understand behaviour and habitat**, and **know how to react safely**. Tone remains factual, friendly, and awareness-focused (not fear-based).

---

## 🔁 Input
- Snake: `{step_data}` (providing at minimum common name and scientific name)

---

## 📁 Output Specification

```json
{{
  "bits": [...],
  "lesson": {{
    "title": "Common name",
    "scientific_name": "Scientific name",
    "aliases": ["Local or alternate name 1", "Local or alternate name 2"],
    "intro": "...",
    "body": "Markdown-formatted content with short paragraphs, ending in a ### Data sheet section.",
    "facts": ["One or two short, surprising, cultural, or safety-related facts."],
    "questions_and_answers": [...],
    "illustrations": ["One short text prompt for illustration."]
  }}
}}
```

---

## 🧱 Schema Details

### 1️⃣ bits
Focus the *CanDo statements* on recognition, safety, and understanding ecological roles. Add one safety-related bit for venomous species.

Example:
```json
[
  {{"title": "I can recognise the Puff Adder.", "description": "Identify its thick body and zigzag pattern.", "order": 1}},
  {{"title": "I can explain where the Puff Adder lives.", "description": "Know its habitat and behaviour.", "order": 2}},
  {{"title": "I know how to act safely around snakes.", "description": "Stay calm and avoid dangerous contact.", "order": 3}}
]
```

---

### 2️⃣ lesson.intro
- 1 sentence hook.
- Descriptive, not alarmist.

Example:
> "A flash of brown among the rocks — the Puff Adder lies still, perfectly camouflaged and waiting for passing prey."

---

### 3️⃣ lesson.body
Write 2–3 short paragraphs (variable length by complexity) covering:
1. **Identification** – colour, markings, size, body shape, typical movement.
2. **Behaviour and habitat** – day/night activity, hunting style, environment.
3. **Venom and human interaction** – danger level, what to do (and not to do), conservation or ecological role.

After the paragraphs, **append** a verified `### Data sheet` in Markdown:

```md
### Data sheet
- **Length:** [in metres or cm]
- **Range:** [geographic range]
- **Colour pattern:** [main ID features]
- **Venom:** [type and danger level, e.g., neurotoxic / cytotoxic / haemotoxic / harmless]
- **Behaviour:** [temperament, movement, or habits]
- **Habitat:** [typical habitats]
- **Diet:** [main prey]
- **Conservation status:** [e.g., common / near-threatened / protected]
```

If any field lacks reliable data, omit it — never write "unknown".

---

### 4️⃣ facts
Include 1–2 concise and engaging facts. Mix **scientific**, **cultural**, or **safety myths**.

Examples:
- "The Black Mamba’s name comes from the dark colour inside its mouth, not its scales."
- "Despite their reputation, most snakes avoid humans if given a chance."
- "Pythons are protected by law in South Africa."

---

### 5️⃣ questions_and_answers
Always include **three multiple-choice questions** in this order:

1. **Identification** — e.g., “Which snake has a hood and can spit venom?”
2. **Habitat or behaviour** — e.g., “Where is the Puff Adder most likely to be found?”
3. **Safety or distinctive trait** — e.g., “What should you do if you encounter this snake?”

Each question must have **4 options** with **one correct** answer and plausible distractors.

Example:
```json
{{
  "question": "What should you do if you see a Puff Adder?",
  "options": [
    {{"text": "Back away slowly and leave it alone.", "correct": true}},
    {{"text": "Try to move it with a stick.", "correct": false}},
    {{"text": "Throw water on it.", "correct": false}},
    {{"text": "Run toward it to scare it off.", "correct": false}}
  ]
}}
```

---

### 6️⃣ illustrations
One short descriptive text prompt suitable for DALL·E or other image generators.

Example:
> "A Puff Adder coiled among dry grass with its head slightly raised in sunlight."

---

## 🧠 Writing Style Guide
- **Tone:** calm, factual, confidence-building; awareness over alarm.
- **Audience:** South Africans — learners, hikers, gardeners, and everyday readers.
- **Avoid:** sensational language (“deadly”, “terrifying”). Use “highly venomous”, “requires caution” instead.
- **Prefer:** simple verbs, concrete images, local contexts (gardens, farms, bushveld).
- **Sentence length:** short to medium (≤ 25 words).
- **Units:** metric (metres, centimetres).
- **Markdown:** include `### Data sheet` exactly as shown.

---

## ⚙️ Generation Instructions for the Agent
1. Fetch or infer verified traits (length, colour pattern, venom type, habitat, diet) from reliable sources (e.g., The Reptile Atlas of Southern Africa, biodiversity databases, museums, Wikipedia/Wikidata as a fallback).
2. Generate `bits`, `intro`, `body`, `facts`, `questions_and_answers`, and `illustrations` as per schema.
3. If the species is **venomous**, include at least **one safety-related** CanDo statement and **one safety-related** question.
4. Validate output JSON — **top-level must be a dict**, not a list.

---

## ✅ Quality Checklist Before Finalising
- [ ] At least **2–3 bits** (include a safety bit for venomous species).
- [ ] Lesson body has **≥ 2 paragraphs** and a `### Data sheet` section.
- [ ] Facts are **engaging** (scientific, cultural, or myth-busting), not repetitive behaviour notes.
- [ ] Exactly **3 questions** with **4 options** each; one clearly correct.
- [ ] Tone promotes **respect and understanding**, not fear.
- [ ] **South African spelling** and **metric units**.
- [ ] **JSON validates** (no trailing commas, correct quoting).