Miami-Dade — design & roadmap
Planning artifacts for porting the school-outcomes platform to Miami-Dade
County Public Schools (M-DCPS, Florida district 13: ~500 schools, ~160 of
them charters, ~321,000 students in 2025-26). Same architecture as the NYC and Philly
builds: a TypeScript Next.js front-end backed by Prisma/Postgres, fed by a
Python sidecar, audited by a read-only validation harness. The methodology
(peer groups, residual-z outliers, comparability regimes, four-check
verification) is lifted from docs/design/; only the source layer — and
one new analytical track — changes.
Contents
| File | What it is |
|---|---|
00_overview.md | Why Miami-Dade, scope, the decisions to settle (M.1–M.11) with recommendations. |
01_inventory.md | Miami-Dade data-source inventory — what is publicly downloadable, verified by fetch. |
02_gap_analysis.md | Miami source layer vs. the NYC/Philly layers, axis by axis. |
03_integration_plan.md | P0–P5 capability sequence, plus the C0–C3 closure track. Status note at the top. |
04_contribution_plan.md | Branch/PR workflow. |
05_validation_spec.md | The four-check taxonomy adapted to Florida sources. |
06_enrollment_capacity_closures.md | New track: enrollment vs. building capacity and the 2026 closure process, modelled on Chalkbeat Chicago's analysis. |
07_runbook.md | Build, load, validate and publish — reproducing the closure track from a clean checkout and refreshing it next year. |
08_review_2026-09-16.md | Adversarial review of the whole build: ranked correctness findings with evidence (13 served-number defects, 12 method/harness items, story and note errors), why the harness missed them, which published conclusions survive, cross-city duplication measurements, ranked refactor plan and schema assessment. No fixes applied. |
09_review_fixes_2026-09-16.md | What the review's fixes changed: per finding, the code change, the reload, the served numbers before and after, the re-validation results (including the new invariants step and its open alarms), and the published conclusions that moved — the parent-survey result does not replicate in its second cohort. |
10_review_2026-09-16b.md | Second adversarial review (correctness only) of the state after the fixes: five new critical items (the 2021-22 staff survey workbook's values are shifted one item against their labels; stale percentiles on suppressed cells; the 2021-22 utilization control on the outcome path; the cost-premium figure's definition; the ablation ranges), major method and inference items, minor text and code items, what holds, and a proposed fix order. All findings applied the same day; §7 records what changed and what it measured, including two further defects found while applying. |
11_accuracy_fixes_2026-09-16.md | Accuracy follow-up: source identity, censored ELL bounds, favorable survey scoring, statistical interpretation, atomic loads, and the exact rebuild/validation status. Supersedes conflicting claims in earlier review records. Addendum: the 2018-19 staff workbook retired (no don't-know column; not comparable under any scoring), exact ELL coverage explained, allowlist upkeep. |
findings.md | First-fetch and first-measurement findings (environment, universe, size tail, five-year trend, utilization, closure-list lift, file shapes). |
sources.yaml | Source registry — same schema as docs/cities/philly/sources.yaml. |
probe/ | The scripts behind findings.md. |
Companion data: data/cities/miami/sources/<source_id>/2026-09-15/provenance.json
(sha256 + bytes + retrieved-at for every fetched file) and
data/cities/miami/reference/ (derived per-school tables: CCD universe with
enrollment, five-year trend, GIS utilization, closure-list overlap).
Conventions inherited
- Validation taxonomy (i)–(iv) as in
verify/METHODOLOGY.mdandpipeline_philly/verify/METHODOLOGY.md. - Branch-per-capability PRs; additive and feature-flagged; NYC and Philly keep working at every commit.
- Python sidecar for discovery/analysis, read-only Python for verification, TypeScript for loaders and the app.
- The working-analysis page idiom (
/philly/methodology/analysis/absenteeism) and proof trees for every served number.
Suggested reading order
00_overview.md → findings.md → 06_enrollment_capacity_closures.md →
01_inventory.md → 02_gap_analysis.md → 03_integration_plan.md →
05_validation_spec.md → 04_contribution_plan.md → sources.yaml.
Status (accuracy corrections: 2026-09-16)
See 11_accuracy_fixes_2026-09-16.md for the latest validation and publication status; earlier review records describe historical snapshots.
- P0 done —
miami_*schema,pipeline_miami/, loader library. - C0–C2 done — 178 source snapshots fetched with provenance; FISH and board-book PDF parsers with two-parser gates; directory, membership (2016-17 → 2025-26), CCD, GIS, FISH, spending, staffing, events and derived loaders; four-check harness PASS (
docs/qa_reports/miami/__enrollment_full_qa.md). - C3 done — packet (
data/analysis/miami-enrollment.json),/miami,/miami/methodology,/miami/methodology/analysis/enrollment,/miami/methodology/metrics/enrollment-capacity,/miami/schools/[school]; navbar tab and search bucket. - P1 done (outcomes) — School Grades components 2018-19, 2021-22 → 2024-25 (every sheet indexed on its own header; the 2022-23 file has four); FAST ELA and Math grades 3–10, Statewide Science 5 and 8, and the B.E.S.T./NGSSS end-of-course exams from 63 spring State Report of Schools files; four-year graduation with subgroups; absenteeism under both state definitions; ADA/ADM attendance; English-learner lower and upper bounds, with an exact share only for uncensored totals, and race shares from the state files for every outcome year (race hidden cells allocated by the rule measured in
probe/race_imputation.py, findings F.15); SESIR incident rates. - P2 done (climate survey) — students, parents and staff workbooks 2018-19 → 2024-25 (20 files; the 2021-22 ones read from their pivot caches) normalised by
pipeline_miami/parse/climate_survey.pyinto per-item tables and a text-matched item crosswalk (data/cities/miami/reference/survey_items.csv); composites over the items asked every year, using agree on positive items and disagree on negative items (unknown responses remain nonfavorable; zero-total distributions are missing); recommend, grade-A/B and response-rate metrics;/miami/methodology/analysis/climate-surveywith the pre-registered sentiment-versus-enrollment test. - P3 done — KNN peer groups on six same-year features with hard filters level | sector | magnet (k = 40, with 20/30 memberships also stored; sensitivity to k has not been evaluated); peer and district-wide percentiles on every rated cell.
- P4 done (harness, outcomes) — base-case components for School Grades, SRS, graduation, absenteeism and survey composites; cross-publisher checks for absenteeism (EDFacts, PK population difference, F.14) and race shares (CCD, process-bound rule, F.15); residual-z independent refit;
docs/qa_reports/miami/__outcomes_validation.md. - P5 done —
/miami/ratings(peer percentile and residual-z methods), outliers and movers,/miami/methodology/metrics/[metric]for every served metric,/miami/methodology/analysis/residual-z,/miami/stories(eight measured story ideas with recipes). - Residual-z —
pipeline_miami/analysis/residual_z.py: WLS per outcome × year on every school with the outcome (closed schools included), z = residual ÷ √(τ² + se²) with τ² the between-school residual variance net of sampling noise (se = 0 for attendance, a share of student-days); pre-registered checks against the state's learning gains (P2 compares Spearman correlations empirically; a demographic gradient does not imply failure by construction. Lowest-quartile gains can include proficient pupils and use the same gain rules); ablation; same-school upper-endpoint ELL sensitivity; flip-diff against the peer percentile; written to additive columns onmiami_school_year_metrics. - Not built — production load (runbook step; no production credentials in this environment); residual-z trend view (slopes within regime); per-item survey drill-down pages; CRDC subgroup discipline; earlier board books' actions in the events table.