# 🪶 Lumabit Bird Lesson Generation Specification

## 🎯 Purpose
Generate JSON lessons for each bird species in the South African bird roadmap, following the Lumabit learning schema. Each output must teach recognition, behaviour, and habitat in a friendly, factual way, suitable for general South African learners.

# INPUT
- Bird: {step_data}

---

## 📁 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 or cultural facts."],
    "questions_and_answers": [...],
    "illustrations": ["One short text prompt for illustration."]
  }}
}}
```

---

## 🧱 Schema Details

### 1️⃣ bits
2–3 concise *CanDo statements* describing what the learner will gain:
```json
[
  {{"title": "I can recognise the [Bird Name].", "description": "Identify its shape and colours.", "order": 1}},
  {{"title": "I can describe where the [Bird Name] lives.", "description": "Understand its typical habitat.", "order": 2}}
]
```
Keep these short and action-based.

---

### 2️⃣ lesson_content.intro
- 1 sentence hook.
- Tone: friendly, natural, and locally contextualised.
- Example:
  > "A bright flash of red and black in the reeds — the Southern Red Bishop is a familiar sight near wetlands."

---

### 3️⃣ lesson_content.body
- 2–3 short paragraphs (variable length by complexity).
- Use plain English, short sentences, and active voice.
- Cover:
  1. Identification and call/name origin
  2. Behaviour, feeding, or nesting habits
  3. Adaptation or human connection (optional)

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

```md
### Data sheet
- **Size:** [in cm]
- **Range:** [verified geographic range]
- **Colours:** [main colours for ID]
- **Beak:** [type and function]
- **Food:** [main diet]
- **Habitat:** [typical habitats]
- **Voice:** [call or song description]
- **Status:** [e.g. common resident / near-threatened]
```

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

---

### 4️⃣ facts
- Include 1–2 **surprising, cultural, or scientific facts** — never behavioural restatements.
- Examples:
  - “The green pigment in the Knysna Turaco’s feathers is unique among birds.”
  - “The Hadeda’s call has become a running joke in South African memes.”

---

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

1. **Identification:** “What is this bird?”
2. **Behaviour/Habitat:** e.g., “Where does it live?” or “What does it eat?”
3. **Distinctive trait:** e.g., “Which colour pattern or call helps identify it?”

Each question must have 4 options with one correct answer and plausible distractors (use similar birds or habitats as alternatives).

Example:
```json
{{
  "question": "What is this bird?",
  "options": [
    {{"text": "Hadeda Ibis", "correct": true}},
    {{"text": "Sacred Ibis", "correct": false}},
    {{"text": "Grey Heron", "correct": false}},
    {{"text": "African Spoonbill", "correct": false}}
  ]
}}
```

---

### 6️⃣ illustrations
One short descriptive text prompt suitable for DALL-E or other image generation models, e.g.:
> "A Southern Masked Weaver hanging upside down while weaving a green grass nest."

---

## 🧠 Writing Style Guide
- **Tone:** friendly, factual, and conversational.
- **Audience:** general South Africans, including learners and adults.
- **Sentence length:** short to medium (max 25 words).
- **Avoid:** jargon, textbook phrasing, or repetitive structure.
- **Prefer:** vivid imagery (“glows orange in the morning sun”), simple verbs, and local references (gardens, parks, farms).
- **Use Markdown headings** (`### Data sheet`) exactly as shown.

---

## ⚙️ Generation Instructions for the Agent

For each bird:
1. Fetch or infer verified traits (length, colours, habitat, etc.) from a reliable source (e.g., BirdLife South Africa, Wikipedia).
2. Generate `bits`, `intro`, `body`, `facts`, `questions_and_answers`, and `illustrations` as per schema.
3. Ensure all text fits the friendly Lumabit tone.
4. Validate JSON before output — top-level must be a **dict**, not a list.


---

## ✅ Quality Checklist Before Finalising
- [ ] Each entry has at least two bits.
- [ ] Lesson body includes at least two paragraphs and a `### Data sheet`.
- [ ] Facts are interesting, not descriptive.
- [ ] Exactly 3 questions with 4 options each.
- [ ] Markdown renders cleanly.
- [ ] All text uses correct South African spelling and metric units.
- [ ] File passes JSON validation.