00 — Overview
1. Why Miami-Dade
- Scale between the two existing builds. ~500 schools (Philly ~300, NYC ~1,800), one district authority (district 13) plus a state department that publishes every school in the same files with the same 4-digit school number. No multi-district reconciliation, no borough/CSD layer.
- A live civic question with a deadline. The School Board closed or consolidated nine schools for 2026-27, flagged 27 more in August 2026, and paused the process in September pending community sessions and a December 2026 decision. Enrollment vs. capacity is the story; nobody has published a school-level, traceable version of it (
06_enrollment_capacity_closures.md). - Strong reference points to validate against. Florida publishes A–F school grades with component scores back to 1999 (the analogue of NYC's Snapshot and Philly's SPREE), a per-school report card, and federal copies of the state's submissions (CCD, EDFacts, CRDC) that serve as independent-publisher checks on day one.
- A district climate survey with the same shape as NYC's (students, parents, staff; ~32 items; school-level workbooks since 2018-19).
- Growth data. FLDOE learning gains (all students and lowest 25%, by grade) are a status-vs-growth distinction NYC lacks, like Philly's PVAAS.
2. Scope (v1)
- Universe: every district-13 school in the FLDOE files — district-run and charter — tagged by type. Virtual programs, DJJ sites, adult centers, alternative and ESE-center schools are included but
include_in_default_comparisons = false. (Charters sponsored outside district 13 — the MSID "districts" KIPP, IDEA, Success Academy — are checked in P0 and tagged if they sit in the county.) - Outcomes: FAST ELA (grades 3–10) and Math (3–8) proficiency and mean scale score; B.E.S.T. Algebra 1 and Geometry, NGSSS Biology, Civics, U.S. History EOCs; FLDOE learning gains; federal 4-year graduation rate (with race and category subgroups); chronic absenteeism (two state definitions); SESIR incident rates; climate-survey rollups; School Grade and its components.
- The closure track: enrollment panel, FISH capacity, per-pupil expenditure, staffing, and a school-events table —
06_…md. - Geography taxonomy: M-DCPS Region (North/Central/South, from the GIS layer), School Board district, city/municipality, zip; attendance-boundary polygons for the map. No community-district analogue.
- Methodology: lift the spec — KNN peer groups with hard filters on level, sector and choice status, soft demographic distance; residual-z outliers; comparability regimes for the FSA→FAST break.
- Out of scope for v1: statewide reference cohorts (Miami vs. similar-demographic Florida schools — attractive but needs a statewide ingest), voucher attribution per school (no public data), Know Your Data Tableau scraping for subgroup assessments.
3. Decisions to settle (with recommendations)
| # | Decision | Recommendation | Why |
|---|---|---|---|
| M.1 | Namespace | Same repo, miami namespace: app/miami/*, miami_* tables, scripts/loaders/miami/, pipeline_miami/, docs/cities/miami/, data/cities/miami/. Copy the Philly pattern; factor a shared pipeline_common/ (download + inspect + provenance) only when the third copy would otherwise diverge. | Proven by Philly (O.1); NYC and Philly untouched. |
| M.2 | Primary key | 4-digit zero-padded school number as text ("0041"), district 13 implicit; carry nces_id (12-digit NCESSCH), msid_* fields, and virtual_provider_number where the accountability files use one. | Every publisher uses the number; padding differs by file (findings.md F.1). |
| M.3 | School-type enum | REGULAR, CHARTER, ALTERNATIVE, ESE_CENTER, TECHNICAL_COLLEGE, VIRTUAL, DJJ, ADULT, from MSID TYPE/SCHL_FUNC_SETTING + School Grades flags + CCD SCH_TYPE. is_charter must agree across MSID, School Grades and CCD (three-way check at load). Tag SCHOOLS_OF_HOPE from MSID CHARTER_SCHL_STAT = H after verifying the code. | Charters are not a number range (M.1). |
| M.4 | Chronic-absenteeism canonical | FLDOE "absent 10% or more" (2017-18 →) as chronic_absenteeism_rate — same definition as NYC and Philly; absent_21plus_rate (2010-11 →) as a second first-class metric; EDFacts 10% with subgroups and CRDC 15+ days as cross-publisher references. | Comparability across cities; the 21+ series gives the long baseline. |
| M.5 | Assessment comparability regimes | FCAT 2.0 (≤ 2013-14) · FSA (2014-15 → 2021-22, no 2019-20) · FAST/B.E.S.T. (2022-23 →, 2022-23 flagged "informational baseline"). Standardized z within regime; raw across with a break marker. 2020-21 participation was opt-in — flag, do not drop. | Same posture as Philly O.4. |
| M.6 | Subgroups | v1 ingests whatever the bulk files carry: race + category for graduation; race for membership; race × sex, IDEA, 504, EL for CRDC absenteeism and discipline; none for assessments (state files are all-students). No Tableau scraping in v1. | Fragile scrapes fail the reproducibility bar. |
| M.7 | Growth as first-class | Yes: learning_gains_ela, learning_gains_math, learning_gains_ela_l25, learning_gains_math_l25 from ELAGains{yy}.xls / MathGains{yy}.xls, plus the School Grades components. | Mirrors Philly O.7 (PVAAS). |
| M.8 | Economic-disadvantage covariate | School Grades Percent of Economically Disadvantaged Students (FLDOE's own NSLP-code definition) as the covariate, with a cep flag from the lunch-status file as a second covariate. Report the CEP caveat wherever the share is shown. | Direct-cert × 1.6 at CEP schools breaks cross-school comparability (findings.md M.8). |
| M.9 | Peer-group features and k | Re-tune on Miami distributions: Black share, Hispanic share, ELL share, econ-disadv share, log enrollment; hard filters on level (ES / MS / HS / K-8 / combination), sector (district vs charter), and choice status (magnet school vs neighborhood). k = 40 with a 20/30/40 flip-diff as in Philly. | 75% Hispanic district: White/Asian shares carry little signal (findings.md M.7). |
| M.10 | Spot-check oracles | (iii-a) same-publisher: School Grades components (achievement = % level 3+ across grades — an aggregation, so ±2 pp) and the Florida Report Cards where a value can be read; (iii-b) independent: NCES CCD (enrollment, staff), EDFacts (absenteeism), CRDC (absenteeism, discipline, course access), M-DCPS Statistical Highlights (district totals). | Philly's "two publishers" advantage exists here on day one. |
| M.11 | Sequencing | Ship the closure track first (C0–C3 in 03_…md), in parallel with P0/P1. | Timely, fetchable now, needs no peer groups. |
4. Inheritance from the NYC and Philly builds
Reused without modification: the methodology spec, the reference scaffold
(engine, outliers, trends, verify), the four-check taxonomy, the front-end
shape (Outliers / Movers / Stories / school pages / methodology hub / proof
trees), the working-analysis page idiom and its full-QA gate, the
discover.py → provenance.json → findings/*.md discovery loop, the
loader _lib pattern, and the contribution workflow.
New and Miami-specific:
- Source connectors for FLDOE (xlsx/xls with per-year header rows and URL forms; the
origin.fldoe.orgrewrite), MSID (session-cookie download), M-DCPS climate workbooks, county GIS REST, and PDF tables (FISH level-of-service report, ABC book). - The school-events table and the enrollment/capacity analysis (
06_…md). - Geography (Region, Board district, attendance boundaries).
- Florida-specific comparability (FSA → FAST) and the A–F school-grade history as a first-class series.
- Story lines: the 2026 closure cohort, charter-sector growth vs district decline, Schools of Hope co-location, the School for Advanced Studies model, magnet vs neighborhood outcomes adjusted for intake, newcomer (immigrant) enrollment collapse, absenteeism after the 2023 definition change.
5. What this branch does not include
Any Miami loader, Prisma model, route, or story. The only code is the
read-only probe/ scripts; the only data are provenance records and small
derived reference tables. NYC and Philly paths are untouched.
6. Next step
Settle M.1–M.11 (all have recommendations; none blocks P0). Then open
miami/repo-setup (P0) and miami/closure-data (C0) as the first two
branches per 03_integration_plan.md.