# 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.org` rewrite), 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`.