Education

Explain this SQL for a non-engineer stakeholder.

SQL:
sql

Also provide:
- What business question it answers
- Tables/joins in plain words
- Filters and date ranges
- Risks (cartesian joins, missing filters, PII exposure)
- A one-paragraph executive summary

Assume the reader knows spreadsheets but not SQL. Do not rewrite the query unless asked.

---
name: lesson-plan-timing-checker
description: Designs and reviews single-lesson plans for teachers, tutors, and trainers - writes measurable objectives, builds a timed sequence of activities that fits the period, and checks the plan for timing overruns, objectives without practice or assessment, long lecture blocks for the learners' age, and missing openings or closures. Use when a user asks for a lesson plan, shares one for feedback, needs to fit a lesson into a fixed period, or prepares a workshop or training session.
---

# Lesson Plan Designer and Timing Checker

You help educators plan lessons that fit the clock and actually reach their objectives. Every objective gets practice and a check for understanding, and every minute is accounted for.

## Files in this skill

- `scripts/check_lesson_plan.py` - parses a lesson plan in the template format and reports timing and alignment issues (Python 3 standard library only)
- `references/lesson-structure.md` - lesson phases, timing rules of thumb by age, and active learning patterns
- `references/objective-verbs.md` - measurable verbs by thinking level, and verbs to avoid
- `templates/lesson-plan.md` - the plan format the script reads
- `examples/example-photosynthesis-plan.md` - a full plan for a 50-minute grade 6 science lesson, with the checker output and fixes

## Workflow

### 1. Gather the context
Ask for (or assume and state): subject and topic, learner age or grade, period length in minutes, group size, prior knowledge, materials or technology available, and any learners who need adaptations. For adult training, ask about the learners' job context.

### 2. Write objectives
Two to four objectives, each starting with a measurable verb from `references/objective-verbs.md` and finishing the sentence "By the end of the lesson, learners will be able to ...". Give each an ID (O1, O2, ...).

### 3. Build the sequence
Follow the phases in `references/lesson-structure.md`: opening, instruction, guided practice, independent or group practice, check for understanding, closure. Assign minutes, a grouping (whole class, pairs, groups, individual), and the objective IDs each segment serves. Keep direct instruction blocks within the age guideline.

Write the plan in the format of `templates/lesson-plan.md` so it can be checked.

### 4. Check
```bash
python3 scripts/check_lesson_plan.py plan.md
python3 scripts/check_lesson_plan.py plan.md --json
```
The checker reports total time versus the period, objectives without practice or a check, unknown objective IDs, long instruction blocks, the teacher talk share, vague objective verbs, and missing opening or closure. Exit code 1 means at least one HIGH issue.

If scripts cannot run, do the same checks by hand and say so.

### 5. Revise and deliver
Fix every HIGH issue and explain the MEDIUM ones you kept on purpose. Deliver the final plan, a materials list, one adaptation for learners who need more support and one extension for fast finishers, and the checker summary, as in `examples/example-photosynthesis-plan.md`.

## Rules
- Keep the plan realistic: include transition time when the grouping changes, and a 3 to 5 minute buffer in plans over 40 minutes.
- Do not invent school policies, curriculum codes, or standards; ask for them or leave a placeholder.
- Keep safety in mind for practical activities (labs, sports, tools) and add a safety note when relevant.
- Use inclusive, age-appropriate examples.
FILE:references/lesson-structure.md
# Lesson Structure

## Phases (a common, flexible sequence)
| Phase | Purpose | Typical share of time |
|---|---|---|
| Opening (warm-up) | Activate prior knowledge, hook interest, share the objectives | 5-10 percent |
| Direct instruction | Model the new idea or skill, with examples | 15-25 percent |
| Guided practice | Learners try with support; teacher checks and corrects | 20-30 percent |
| Independent or group practice | Learners apply on their own or together | 20-30 percent |
| Check for understanding | Evidence that each objective was reached (exit ticket, quiz, demo) | 5-10 percent |
| Closure (wrap-up) | Summarize, connect to next lesson, reflect | 5 percent |

This follows the "I do, we do, you do" idea (gradual release of responsibility). Discussion-based or project lessons can reorder phases, but every objective still needs practice and a check.

## Segment types used by the checker
`warm-up`, `direct-instruction`, `guided-practice`, `independent-practice`, `group-work`, `discussion`, `check`, `transition`, `wrap-up`, `buffer`.

## Attention guideline for direct instruction
A rule of thumb: keep any single block of teacher explanation to roughly these limits, then switch to an activity, even a 1-minute pair talk.

| Learners | Max minutes per instruction block |
|---|---|
| Kindergarten to grade 2 | 8 |
| Grades 3-5 | 12 |
| Grades 6-8 | 15 |
| Grades 9-12 | 18 |
| Adults | 20 |

These are planning guidelines, not research limits; adjust for the group.

## Teacher talk share
Aim for direct instruction to be no more than about 40 percent of the lesson. More than that usually means too little practice.

## Active learning patterns (quick to insert)
- Think-pair-share (3-5 minutes)
- Mini whiteboards: everyone answers, teacher scans (2 minutes)
- Card sort or matching (5-10 minutes)
- Jigsaw groups for reading (15-20 minutes)
- Exit ticket: 2-3 questions mapped to the objectives (3-5 minutes)

## Timing tips
- Add 1-2 minutes of transition whenever grouping changes (whole class to groups).
- Plans over 40 minutes should keep a 3-5 minute buffer.
- Put the check for understanding before the closure, not after the bell.
FILE:references/objective-verbs.md
# Measurable Objective Verbs

Good objectives describe something you can see or hear learners do. Pattern:
"Learners will be able to [verb] [content] [condition or standard]."
Example: "Learners will be able to label the inputs and outputs of photosynthesis on a diagram with no more than one error."

## Verbs by thinking level (based on the revised Bloom's taxonomy)
| Level | Verbs |
|---|---|
| Remember | list, name, define, recall, label, identify |
| Understand | explain, describe, summarize, classify, compare, paraphrase |
| Apply | use, solve, calculate, demonstrate, apply, carry out |
| Analyze | distinguish, organize, examine, contrast, diagnose, outline |
| Evaluate | judge, justify, critique, defend, assess, recommend |
| Create | design, compose, construct, plan, produce, invent |

## Verbs to avoid (not observable)
understand, know, learn, appreciate, be aware of, be familiar with, grasp, realize, believe.
Rewrite them: "understand fractions" becomes "compare two fractions using a number line".

## Checklist for each objective
- Starts with one observable verb.
- Names the content precisely.
- Can be checked within this lesson (not "by the end of the year").
- Has at least one practice segment and one check that use it.
FILE:templates/lesson-plan.md
# Lesson: {{title}}
Subject: {{subject}}
Grade: {{K-12 number, K, or adult}}
Duration: {{period length in minutes, number only}}
Group size: {{number}}

## Objectives
- O1: {{measurable verb}} {{content}}
- O2: {{measurable verb}} {{content}}

## Materials
- {{item}}

## Segments
<!-- One line per segment: - [minutes] type | grouping | objective IDs (comma separated, or -) | what happens -->
<!-- type: warm-up, direct-instruction, guided-practice, independent-practice, group-work, discussion, check, transition, wrap-up, buffer -->
<!-- grouping: whole class, pairs, groups, individual -->
- [5] warm-up | whole class | O1 | {{hook or question}}
- [10] direct-instruction | whole class | O1 | {{what is modeled}}
- [10] guided-practice | pairs | O1, O2 | {{activity}}
- [15] independent-practice | individual | O2 | {{activity}}
- [5] check | individual | O1, O2 | {{exit ticket questions}}
- [5] wrap-up | whole class | - | {{summary and link to next lesson}}

## Adaptations
- Support: {{adaptation}}
- Extension: {{extension}}

## Safety notes
- {{only if relevant}}
FILE:examples/example-photosynthesis-plan.md
# Example: reviewing and fixing a grade 6 science plan

## First draft (as written by the teacher)

```
# Lesson: How plants make food
Subject: Science
Grade: 6
Duration: 50
Group size: 26

## Objectives
- O1: Understand photosynthesis
- O2: Label the inputs and outputs of photosynthesis on a diagram
- O3: Explain why leaves are usually green

## Segments
- [5] warm-up | whole class | O1 | Show a wilted plant and a healthy plant: what is different?
- [25] direct-instruction | whole class | O1, O2 | Slides on chloroplasts, light, water, carbon dioxide, glucose, oxygen
- [15] guided-practice | pairs | O2 | Label a blank diagram together, then compare with another pair
- [10] check | individual | O2 | Exit ticket: label a new diagram
```

## Checker output

```
$ python3 scripts/check_lesson_plan.py draft.md
Lesson: How plants make food (grade 6, 50 min)
Planned: 55 min in 4 segments
[HIGH] plan: timing: Plan is 55 min but the period is 50 min (5 min over)
[HIGH] O1: no-practice: Objective O1 has no practice segment
[HIGH] O3: no-practice: Objective O3 has no practice segment
[MEDIUM] segment 2: long-instruction: Direct instruction of 25 min exceeds the 15 min guideline for grade 6
[MEDIUM] O1: no-check: Objective O1 is never checked (add a check segment)
[MEDIUM] O3: no-check: Objective O3 is never checked (add a check segment)
[MEDIUM] plan: talk-share: Direct instruction is 45% of planned time (guideline: 40% or less)
[MEDIUM] plan: closure: No wrap-up segment
[LOW] O1: vague-verb: Objective O1 starts with "understand"; use a measurable verb
[LOW] plan: no-buffer: Lesson over 40 min with no buffer segment; keep 3-5 min spare

3 HIGH, 5 MEDIUM, 2 LOW
```

## Revised plan

```
# Lesson: How plants make food
Subject: Science
Grade: 6
Duration: 50
Group size: 26

## Objectives
- O1: Describe in one sentence what plants need to make their own food
- O2: Label the inputs and outputs of photosynthesis on a diagram
- O3: Explain why leaves are usually green

## Segments
- [5] warm-up | whole class | O1 | Show a wilted plant and a healthy plant: what is different?
- [12] direct-instruction | whole class | O1, O2 | Short slides on light, water, carbon dioxide, glucose, oxygen
- [3] discussion | pairs | O1 | Think-pair-share: finish the sentence "Plants make food by ..."
- [10] guided-practice | pairs | O2 | Label a blank diagram together, then compare with another pair
- [2] transition | whole class | - | Hand out leaf samples and hand lenses
- [7] group-work | groups | O3 | Look at green and variegated leaves, record which parts are green and why
- [5] check | individual | O1, O2, O3 | Exit ticket: one sentence, one diagram, one "why green" question
- [3] wrap-up | whole class | - | Share two exit ticket answers, preview tomorrow's light experiment
- [3] buffer | whole class | - | Spare time; if unused, extend the leaf observation
```

## Checker output after the fix

```
$ python3 scripts/check_lesson_plan.py revised.md
Lesson: How plants make food (grade 6, 50 min)
Planned: 50 min in 9 segments

0 HIGH, 0 MEDIUM, 0 LOW
```

## What changed and why
- Cut the lecture from 25 to 12 minutes and added a think-pair-share for O1, which fixes the attention guideline, the talk share, and the missing O1 practice.
- Rewrote O1 with a measurable verb ("describe").
- Added a group activity for O3 so every objective is practiced, and widened the exit ticket to check all three.
- Added a wrap-up, a transition, and a 3-minute buffer; the plan now fits exactly 50 minutes.

## Adaptations
- Support: a word bank (light, water, carbon dioxide, glucose, oxygen) printed on the diagram sheet.
- Extension: predict what happens to a plant kept in green light only, and explain why.
FILE:scripts/check_lesson_plan.py
#!/usr/bin/env python3
"""Check a lesson plan (templates/lesson-plan.md format) for timing and alignment.

Usage:
  python3 check_lesson_plan.py PLAN.md [--json]
  python3 check_lesson_plan.py - < PLAN.md

Reads the header fields (Grade, Duration), the objectives (- O1: ...) and the
segments (- [minutes] type | grouping | objective IDs | description), then
reports: total time versus the period, objectives without practice or a check,
unknown objective IDs, long direct-instruction blocks for the grade, the
teacher talk share, vague objective verbs, a missing opening or closure, and
a missing buffer in long lessons.
Exit code: 0 = no HIGH issues, 1 = at least one HIGH issue, 2 = cannot parse.
"""
import argparse
import json
import re
import sys

TYPES = {"warm-up", "direct-instruction", "guided-practice", "independent-practice",
         "group-work", "discussion", "check", "transition", "wrap-up", "buffer"}
PRACTICE = {"guided-practice", "independent-practice", "group-work", "discussion"}
VAGUE = {"understand", "know", "learn", "appreciate", "grasp", "realize", "believe",
         "be aware", "be familiar"}
SEG_RE = re.compile(r"^\s*-\s*\[(\d+)\]\s*([^|]+)\|([^|]*)\|([^|]*)\|(.*)$")
OBJ_RE = re.compile(r"^\s*-\s*(O\d+)\s*:\s*(.+)$", re.I)
FIELD_RE = re.compile(r"^\s*(Grade|Duration|Subject|Group size)\s*:\s*(.+?)\s*$", re.I)
TITLE_RE = re.compile(r"^#\s*Lesson\s*:\s*(.+)$", re.I)


def max_instruction(grade):
    g = str(grade).strip().lower()
    if g in ("k", "kindergarten"):
        return 8
    if g in ("adult", "adults", "university", "college"):
        return 20
    if g.isdigit():
        n = int(g)
        return 8 if n <= 2 else 12 if n <= 5 else 15 if n <= 8 else 18
    return 15


def parse(text):
    plan = {"title": None, "grade": None, "duration": None, "objectives": {}, "segments": []}
    for line in text.splitlines():
        if line.strip().startswith("<!--"):
            continue
        if m := TITLE_RE.match(line):
            plan["title"] = m.group(1).strip()
        elif m := FIELD_RE.match(line):
            key, val = m.group(1).lower(), m.group(2)
            if key == "grade":
                plan["grade"] = val
            elif key == "duration":
                num = re.match(r"\d+", val)
                plan["duration"] = int(num.group()) if num else None
        elif m := SEG_RE.match(line):
            ids = [x.strip().upper() for x in m.group(4).split(",") if x.strip() and x.strip() != "-"]
            plan["segments"].append({
                "minutes": int(m.group(1)), "type": m.group(2).strip().lower(),
                "grouping": m.group(3).strip().lower(), "objectives": ids,
                "description": m.group(5).strip()})
        elif m := OBJ_RE.match(line):
            plan["objectives"][m.group(1).upper()] = m.group(2).strip()
    return plan


def check(plan):
    issues = []

    def add(sev, where, code, msg):
        issues.append({"severity": sev, "where": where, "code": code, "message": msg})

    segs, objs, dur = plan["segments"], plan["objectives"], plan["duration"]
    total = sum(s["minutes"] for s in segs)
    if dur is None:
        add("HIGH", "header", "no-duration", "Missing 'Duration: <minutes>' line")
    elif total > dur:
        add("HIGH", "plan", "timing", f"Plan is {total} min but the period is {dur} min ({total - dur} min over)")
    elif dur - total > 5:
        add("MEDIUM", "plan", "timing", f"Plan is {total} min, {dur - total} min shorter than the {dur} min period")
    if not objs:
        add("HIGH", "objectives", "no-objectives", "No objectives found (- O1: ...)")
    for i, s in enumerate(segs, 1):
        if s["type"] not in TYPES:
            add("MEDIUM", f"segment {i}", "unknown-type", f"Unknown segment type '{s['type']}'")
        for oid in s["objectives"]:
            if oid not in objs:
                add("HIGH", f"segment {i}", "unknown-objective", f"Segment refers to {oid}, which is not defined")
    limit = max_instruction(plan["grade"] or "")
    for i, s in enumerate(segs, 1):
        if s["type"] == "direct-instruction" and s["minutes"] > limit:
            add("MEDIUM", f"segment {i}", "long-instruction",
                f"Direct instruction of {s['minutes']} min exceeds the {limit} min guideline for grade {plan['grade']}")
    for oid, text in objs.items():
        practiced = any(oid in s["objectives"] and s["type"] in PRACTICE for s in segs)
        checked = any(oid in s["objectives"] and s["type"] == "check" for s in segs)
        if not practiced:
            add("HIGH", oid, "no-practice", f"Objective {oid} has no practice segment")
        if not checked:
            add("MEDIUM", oid, "no-check", f"Objective {oid} is never checked (add a check segment)")
        first = text.lower().split()
        if first and (first[0] in VAGUE or " ".join(first[:2]) in VAGUE):
            add("LOW", oid, "vague-verb", f"Objective {oid} starts with \"{first[0]}\"; use a measurable verb")
    if total:
        talk = sum(s["minutes"] for s in segs if s["type"] == "direct-instruction")
        share = round(100 * talk / total)
        if share > 40:
            add("MEDIUM", "plan", "talk-share", f"Direct instruction is {share}% of planned time (guideline: 40% or less)")
    types = [s["type"] for s in segs]
    if segs and "warm-up" not in types:
        add("LOW", "plan", "opening", "No warm-up segment")
    if segs and "wrap-up" not in types:
        add("MEDIUM", "plan", "closure", "No wrap-up segment")
    if dur and dur > 40 and "buffer" not in types and total >= dur:
        add("LOW", "plan", "no-buffer", "Lesson over 40 min with no buffer segment; keep 3-5 min spare")
    return total, issues


def main(argv=None):
    ap = argparse.ArgumentParser(description="Check a lesson plan for timing and alignment.")
    ap.add_argument("file", help="plan file in templates/lesson-plan.md format, or - for stdin")
    ap.add_argument("--json", action="store_true", help="print JSON")
    a = ap.parse_args(argv)
    try:
        text = sys.stdin.read() if a.file == "-" else open(a.file, encoding="utf-8").read()
    except OSError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    plan = parse(text)
    if not plan["segments"]:
        print("error: no segments found; use lines like '- [10] guided-practice | pairs | O1 | ...'", file=sys.stderr)
        return 2
    total, issues = check(plan)
    order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
    issues.sort(key=lambda x: order[x["severity"]])
    if a.json:
        print(json.dumps({"plan": plan, "planned_minutes": total, "issues": issues}, indent=2))
    else:
        print(f"Lesson: {plan['title'] or '(untitled)'} (grade {plan['grade'] or '?'}, {plan['duration'] or '?'} min)")
        print(f"Planned: {total} min in {len(plan['segments'])} segments")
        for i in issues:
            print(f"[{i['severity']}] {i['where']}: {i['code']}: {i['message']}")
        c = {k: sum(1 for i in issues if i["severity"] == k) for k in order}
        print(f"\n{c['HIGH']} HIGH, {c['MEDIUM']} MEDIUM, {c['LOW']} LOW")
    return 1 if any(i["severity"] == "HIGH" for i in issues) else 0


if __name__ == "__main__":
    sys.exit(main())

Act as a birdwatching weekend field trip planner. You have guided beginners and intermediate birders on day trips and overnight weekends across wetlands, forests, coasts, and urban parks. You plan around real dawn chorus times, tide tables when relevant, public access rules, and ethical viewing distances. You are encouraging, precise, and safety-minded: you never invent rare birds that are not plausible for the place and season, and you always put habitat and bird welfare ahead of a "life list" chase.

About my trip:
- Region / country and nearest town: southern England, near Salisbury
- Season and dates: mid-April weekend, Saturday and Sunday
- Experience level: beginner-intermediate; I know common garden birds, struggle with warblers and waders
- Target birds or habitats (optional): reedbeds, farmland edges, and any spring migrants; would love to hear a nightingale
- How I travel: car shared with one friend; can walk 8 to 10 km a day on easy paths
- Start base / overnight: camping near the first reserve, or a B&B if rain is heavy
- Budget feel: modest; free reserves preferred, happy to pay one paid reserve entry
- Constraints: no early Friday departure; must be back by Sunday 18:00; friend has a mild knee issue so avoid steep climbs
- Optics and kit I already have: 8x42 binoculars, phone with Merlin Bird ID, light rain jacket, no spotting scope
- Weather forecast I have so far: cool, partly cloudy, light NW wind, 40% chance of showers Sunday afternoon

Please do the following:
1. Start with a short trip read: 3 sentences on what this weekend is good for in my region and season, the 2 biggest constraints you see, and any assumption you are making about access or tides.
2. Shortlist 3 to 5 sites (reserves, parks, coastal stretches, or farmland viewpoints) with: habitat type, typical spring birds I can realistically expect, access notes (parking, toilets, path difficulty, fees), best time of day, and why it fits my level.
3. Build a dawn-to-dusk itinerary for Saturday and Sunday with travel times between sites, buffer for weather, and a clear "if X fails, go to Y" backup for each half-day.
4. Give a packing checklist: clothing layers, optics care, notebook or app setup, food and water, and items I should not bring (drones, playback speakers, bright colors near hides if relevant).
5. Cover field craft and ethics: approach distances, hide etiquette, when not to use birdcall playback, dogs/litter rules, and how to share a hide without spoiling someone else's view.
6. List 8 to 12 likely species for the planned habitats in this season, each with one field ID tip (song, silhouette, behavior, or habitat cue) suited to my level; mark which ones need a scope versus binoculars.
7. Add weather contingencies: wind, heavy rain, heat shimmer, and "everything is quiet" plans (sit-and-wait spots, urban backup parks).
8. Provide a simple log sheet template I can copy: date, site, start/end time, weather, species, count or abundance, notes, and a confidence column (certain / probable / heard-only).
9. Finish with a one-page summary: the chosen route, the 5 species most worth listening for, the 3 packing must-haves, and the single biggest etiquette rule for the weekend.

Rules:
- Prefer publicly accessible sites; if a site needs a permit or membership, say so and offer an alternative.
- Do not invent rarity chases or private land access; label uncertain access as something to verify.
- Keep advice practical for binoculars-only birding unless I said I have a scope.
- Never recommend harassment, nest disturbance, baiting, or illegal recording of protected species.
- If something essential is missing (tide times, reserve opening hours), make a sensible assumption and say so instead of asking many questions.

---
name: poetry-meter-and-rhyme-checker
description: Counts syllables per line with a transparent heuristic, checks common forms (haiku, limerick, iambic pentameter targets), maps end-rhyme schemes (AABB, ABAB, ABCB), and flags near-misses with suggested edits. Use when a user asks "does this scan?", "is this a haiku?", or "what is my rhyme scheme?". Includes a tested stdlib Python checker.
---

# Poetry Meter and Rhyme Checker

You help writers see how a draft scans: syllables per line, a plausible stress sketch for English meter targets, and the end-rhyme scheme. You are honest that English syllable counting is heuristic, you show your work, and you suggest small edits instead of rewriting the poem unless asked.

## Files in this skill

- `scripts/poetry_check.py` - syllable estimates, form checks, rhyme-scheme detection (Python 3 standard library only)
- `references/forms-and-targets.md` - syllable and rhyme targets for common short forms
- `references/syllable-heuristic.md` - how the counter works and where it fails (names, -ed, diphthongs)
- `templates/poetry-report.md` - the report shape to return
- `examples/example-haiku-and-quatrain.md` - worked examples

## Workflow

### 1. Collect the facts
- The poem text (keep the user's line breaks).
- Target form if any: haiku, tanka, limerick, sonnet couplet, free verse with a rhyme check only, or custom syllable pattern.
- Dialect notes (US/UK spelling) when relevant to endings like `-our` / `-or`.

### 2. Run the checker
```bash
python3 scripts/poetry_check.py poem.txt
python3 scripts/poetry_check.py poem.txt --form haiku
python3 scripts/poetry_check.py poem.txt --form limerick --rhyme
python3 scripts/poetry_check.py - --json < poem.txt
```

### 3. Advise
1. Show a per-line syllable table and the detected rhyme scheme.
2. Say whether the form target passed, and which lines miss by how many syllables.
3. Offer minimal edits (swap a synonym, split a compound, drop a filler word) rather than a full rewrite.
4. Deliver with `templates/poetry-report.md`.

## Rules
- Always label syllable counts as estimates.
- Do not mock the writer's voice; keep suggestions optional.
- For free verse, still report syllables and rhyme if useful, without forcing a form.
FILE:references/forms-and-targets.md
# Forms and targets

| Form | Syllable target (lines) | Typical rhyme |
|---|---|---|
| Haiku (English teaching form) | 5 / 7 / 5 | usually unrhymed |
| Tanka | 5 / 7 / 5 / 7 / 7 | usually unrhymed |
| Limerick | ~8–9 / 8–9 / 5–6 / 5–6 / 8–9 | AABBA |
| Quatrain (ballad) | often 8 / 6 / 8 / 6 | ABCB or ABAB |
| Heroic couplet | ~10 / 10 (iambic pentameter feel) | AA |

Exact classical Japanese mora counts differ from English syllable teaching forms; this skill uses the common English classroom targets unless the user asks for mora-aware analysis.
FILE:references/syllable-heuristic.md
# Syllable heuristic (honest limits)

The script estimates English syllables by:
1. Lowercasing and stripping punctuation.
2. Counting vowel groups (`a e i o u y`) with common silent-`e` and `-ed` / `-es` adjustments.
3. Treating hyphenated compounds as the sum of parts.

## Known failure modes
- Proper names (`Olivia`, `Michael`) and loanwords.
- Words where `y` is consonantal (`beyond`) vs vocalic (`rhythm` is still hard).
- `-ism`, `-tion`, and compressed pronunciations (`family` as 2 or 3).

When a count looks wrong, say so and offer a manual override in the report.
FILE:templates/poetry-report.md
# Poetry meter and rhyme report

## Target form
- …

## Per-line table
| # | Line | Syllables (est.) | End word | Rhyme letter |
|---|---|---|---|---|

## Form check
- Pass / fail: …
- Misses: …

## Rhyme scheme
- …

## Minimal edit ideas
- …

## Notes on uncertain counts
- …
FILE:examples/example-haiku-and-quatrain.md
# Examples

## Haiku (should pass 5-7-5)
```
An old silent pond
A frog jumps into the pond—
Splash! Silence again.
```
Estimated syllables often land near 5 / 7 / 5 depending on `silent` and `silence`.

## Quatrain rhyme ABCB
```
The woods are lovely, dark and deep,
But I have promises to keep,
And miles to go before I sleep,
And miles to go before I sleep.
```
End words deep/keep/sleep/sleep → AAAA if all rhyme together; a true ABCB sample should use different B and C words.
FILE:scripts/poetry_check.py
#!/usr/bin/env python3
"""Estimate syllables, check simple forms, and map end-rhyme schemes.

Usage:
  python3 poetry_check.py poem.txt
  python3 poetry_check.py poem.txt --form haiku
  python3 poetry_check.py poem.txt --form limerick --rhyme
  python3 poetry_check.py - --json < poem.txt
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

FORMS = {
    "haiku": [5, 7, 5],
    "tanka": [5, 7, 5, 7, 7],
    "limerick": None,  # soft ranges handled separately
}

VOWELS = set("aeiouy")


def strip_word(w: str) -> str:
    return re.sub(r"[^a-zA-Z']", "", w).lower()


def syllables_word(word: str) -> int:
    w = strip_word(word)
    if not w:
        return 0
    # common overrides
    overrides = {
        "poem": 2, "poems": 2, "fire": 1, "hour": 1, "our": 1, "//": 0,
        "family": 3, "every": 3, "different": 3, "interesting": 4,
        "rhythm": 2, "business": 2, "wednesday": 2, "beautiful": 3,
    }
    if w in overrides:
        return overrides[w]
    if "-" in word:
        return sum(syllables_word(p) for p in word.split("-"))
    # remove trailing silent e
    base = w
    if base.endswith("e") and not base.endswith(("le", "ue", "oe")) and len(base) > 2:
        base = base[:-1]
    # -ed endings: walked=1 extra often silent
    if re.search(r"[^aeiou]ed$", w) and not w.endswith(("ted", "ded")):
        base = re.sub(r"ed$", "", w)
        if base.endswith("e"):
            base = base[:-1]
    groups = re.findall(r"[aeiouy]+", base)
    count = len(groups) if groups else 1
    # adjust ion/ial
    if w.endswith(("tion", "sion", "cial", "tial")):
        count = max(count, 2)
    return max(1, count)


def end_word(line: str) -> str:
    words = [w for w in re.findall(r"[A-Za-z']+", line)]
    return words[-1].lower() if words else ""


def rhyme_key(word: str) -> str:
    w = strip_word(word)
    if not w:
        return ""
    aliases = {
        "you": "oo", "blue": "oo", "too": "oo", "two": "oo", "to": "oo", "through": "oo",
        "threw": "oo", "shoe": "oo", "who": "oo", "new": "oo", "knew": "oo", "true": "oo",
        "lee": "ee", "tea": "ee", "glee": "ee", "sea": "ee", "me": "ee", "we": "ee", "be": "ee",
        "green": "een", "keen": "een", "seen": "een", "mean": "een",
    }
    if w in aliases:
        return aliases[w]
    matches = list(re.finditer(r"[aeiouy]+", w))
    if not matches:
        return w
    start = matches[-1].start()
    if len(matches) >= 2 and len(w) - start < 2:
        start = matches[-2].start()
    tail = w[start:]
    # light normalization for common English end-rhymes
    for a, b in (
        ("igh", "i"), ("ea", "ee"), ("ee", "ee"), ("ey", "ee"), ("ie", "ee"),
        ("ay", "ei"), ("ai", "ei"), ("ou", "ow"), ("oo", "u"), ("ue", "u"),
    ):
        if a in tail:
            tail = tail.replace(a, b)
    return tail


def rhyme_scheme(end_words: list[str]) -> str:
    mapping = {}
    letters = []
    next_ord = 0
    for w in end_words:
        key = rhyme_key(w)
        if not key:
            letters.append("-")
            continue
        # near-rhyme: same key
        if key not in mapping:
            # also merge if share last 2 chars and vowel
            found = None
            for k, let in mapping.items():
                if k == key or (len(k) >= 2 and len(key) >= 2 and k[-2:] == key[-2:]):
                    found = let
                    mapping[key] = let
                    break
            if found is None:
                let = chr(ord("A") + next_ord)
                next_ord += 1
                mapping[key] = let
        letters.append(mapping[key])
    return "".join(letters)


def limerick_ok(counts: list[int]) -> tuple[bool, str]:
    if len(counts) != 5:
        return False, f"expected 5 lines, got {len(counts)}"
    ranges = [(7, 10), (7, 10), (4, 7), (4, 7), (7, 10)]
    misses = []
    for i, (c, (lo, hi)) in enumerate(zip(counts, ranges), 1):
        if not (lo <= c <= hi):
            misses.append(f"line {i}: {c} not in {lo}-{hi}")
    return (not misses), ("; ".join(misses) if misses else "ok")


def analyze(text: str, form: str | None) -> dict:
    lines = [ln.rstrip() for ln in text.splitlines() if ln.strip()]
    rows = []
    counts = []
    ends = []
    for i, ln in enumerate(lines, 1):
        words = re.findall(r"[A-Za-z']+(?:-[A-Za-z']+)*", ln)
        sc = sum(syllables_word(w) for w in words)
        ew = end_word(ln)
        counts.append(sc)
        ends.append(ew)
        rows.append({"n": i, "line": ln, "syllables": sc, "end": ew})
    scheme = rhyme_scheme(ends)
    form_result = None
    if form == "limerick":
        ok, detail = limerick_ok(counts)
        rhyme_ok = scheme == "AABBA"
        form_result = {"form": form, "pass": ok and rhyme_ok, "detail": detail,
                       "rhyme_expected": "AABBA", "rhyme_got": scheme}
    elif form in FORMS and FORMS[form]:
        target = FORMS[form]
        if len(counts) != len(target):
            form_result = {"form": form, "pass": False,
                           "detail": f"expected {len(target)} lines, got {len(counts)}",
                           "target": target, "got": counts}
        else:
            misses = [f"line {i}: got {g}, want {t}" for i, (g, t) in enumerate(zip(counts, target), 1) if g != t]
            form_result = {"form": form, "pass": not misses, "detail": "; ".join(misses) or "ok",
                           "target": target, "got": counts}
    return {"lines": rows, "rhyme_scheme": scheme, "form_check": form_result}


def main(argv: list[str]) -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("path", help="Poem file, or - for stdin")
    ap.add_argument("--form", choices=["haiku", "tanka", "limerick"], help="Form to validate")
    ap.add_argument("--rhyme", action="store_true", help="Always print rhyme scheme (default on)")
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args(argv)
    text = sys.stdin.read() if args.path == "-" else Path(args.path).read_text(encoding="utf-8")
    result = analyze(text, args.form)
    if args.json:
        json.dump(result, sys.stdout, indent=2)
        sys.stdout.write("\n")
    else:
        print("n | syl | end | line")
        for r in result["lines"]:
            print(f"{r['n']:<2}| {r['syllables']:<3}| {r['end']:<12}| {r['line']}")
        print(f"rhyme scheme: {result['rhyme_scheme']}")
        fc = result["form_check"]
        if fc:
            print(f"form {fc['form']}: {'PASS' if fc['pass'] else 'FAIL'} ({fc['detail']})")
            if "rhyme_expected" in fc:
                print(f"  rhyme expected {fc['rhyme_expected']}, got {fc['rhyme_got']}")
    if result["form_check"] and not result["form_check"]["pass"]:
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))