Standards Core

Standards-Core

What this Skill does

Given one or more PDF textbooks (teacher + student editions), produce:

• coverage_matrix.csv / .json — standard ↔ {taught, practiced, assessed}, intensity, off-grade flags, redundancy.
• evidence.jsonl — for each standard: top page hits with quoted spans and book_id:page:start:end anchors.
• pages.jsonl — page-level text index (one JSON object per page).

How to run

1. Prefer the installed document-skills/pdf to extract page text and tables. If not present, fall back to pdftotext (if available).
2. Build a page index: write outputs/pages.jsonl with {book_id, page, text}.
3. Load a standards pack (YAML) defining standards, grade ranges, and keyword lexicons.
4. Run scripts/align_standards.py to propose hits, then refine with LLM judgments for borderline matches.
5. Compute coverage, off-grade %, and redundancy per standard; write to outputs/coverage.json and outputs/coverage.csv.
6. For each standard with a rating, capture ≥1 quoted span + page anchor in outputs/evidence.jsonl. If none found, mark: "unrated": "evidence not found".

Inputs (ask the user or read CLI args)

• subject: math|ela
• grades: e.g., 3–5
• standards_pack: path to YAML (CCSS or state) with id, grade, keywords[], anti_keywords[], examples[]
• pdfs: list of files
• out_dir: outputs/

Deterministic first, generative second

• Use Python scripts for parsing, counting, CSV/JSON writing.
• Use the model only for disambiguation (e.g., near-miss span classification) and for short rationales.

Scripts to call

• scripts/align_standards.py --pages outputs/pages.jsonl --standards standards/<pack>.yaml --subject {math|ela} --grades <range> --out outputs

Evidence requirements

• Do NOT claim a standard is covered without at least one quoted span and page anchor.
• If evidence is missing, set the status "unrated": "evidence not found" and surface a TODO.

Minimal standards pack example (save as standards/ccss_math_sample.yaml)

standards:
  - id: "3.NF.A.1"
    grade: 3
    keywords: ["fraction", "equal parts", "numerator", "denominator"]
    anti_keywords: ["percent"]
  - id: "4.OA.A.3"
    grade: 4
    keywords: ["multi-step", "word problem", "interpret", "remainders"]
    anti_keywords: []

Output file formats

coverage.json

{
  "metadata": {
    "subject": "math",
    "grades": "3-5",
    "books": ["math_grade3.pdf"],
    "total_standards": 15
  },
  "standards": [
    {
      "id": "3.NF.A.1",
      "grade": 3,
      "taught": true,
      "practiced": true,
      "assessed": false,
      "intensity": "high",
      "off_grade_percent": 5,
      "redundancy_count": 2,
      "evidence_found": true,
      "top_pages": [12, 15, 18],
      "rationale": "Clear instruction with multi-page practice problems"
    },
    {
      "id": "3.NF.A.1",
      "grade": 3,
      "taught": false,
      "practiced": false,
      "assessed": false,
      "intensity": "none",
      "off_grade_percent": 0,
      "redundancy_count": 0,
      "evidence_found": false,
      "unrated": "evidence not found"
    }
  ],
  "summary": {
    "total_covered": 12,
    "total_uncovered": 3,
    "coverage_percent": 80
  }
}

evidence.jsonl (one object per line)

{"standard": "3.NF.A.1", "pages": [12, 15, 18], "top_hit": {"page": 12, "book_id": "math_grade3", "quote": "A fraction is an equal part of a whole", "anchor": "math_grade3:12:45:92", "context": "Instruction section on Understanding Fractions"}}
{"standard": "3.NF.A.2", "pages": [20], "top_hit": {"page": 20, "book_id": "math_grade3", "quote": "On a number line, locate 1/2, 1/3, 1/4", "anchor": "math_grade3:20:120:165", "context": "Practice worksheet"}}
{"standard": "4.OA.A.1", "unrated": "evidence not found"}

pages.jsonl (one object per page)

{"book_id": "math_grade3", "page": 1, "text": "Chapter 1: Understanding Numbers... [page content]"}
{"book_id": "math_grade3", "page": 2, "text": "Lesson 1.1: Counting and Place Value... [page content]"}

Workflow example

# 1. Extract and index PDF pages
scripts/align_standards.py --extract-pages math_grade3.pdf --out outputs

# 2. Run standards alignment
scripts/align_standards.py \
  --pages outputs/pages.jsonl \
  --standards standards/ccss_math_grade3.yaml \
  --subject math \
  --grades 3 \
  --out outputs

# 3. Review outputs
# - outputs/coverage.json
# - outputs/coverage.csv
# - outputs/evidence.jsonl

Error handling

• If a PDF cannot be read, log and skip with a warning.
• If a standards pack is malformed, halt with a descriptive error.
• If no evidence is found for a standard, mark unrated and raise a TODO comment for manual review.