00 — Overview
1. Why Philadelphia
Philadelphia is structurally simpler than NYC (one school district instead of 32 community districts; ~300 schools instead of ~1,800) and has data sources that are as good or better than NYC's on every axis the current platform exercises. The same analytical machinery — peer groups, residual-z outliers, comparability regimes, the four-check verification harness — drops in once the source layer is rewritten.
The civic case: the District publishes a serious official report (SPREE) and the state publishes a comparable accountability index (Future Ready PA Index), so there is a reference point to validate against and improve on — same posture as the NYC build vs. NYC's School Quality Snapshot.
2. Scope (v1)
- Universe: School District of Philadelphia district schools + Philadelphia-located brick-and-mortar charter and Renaissance Charter schools (≈210 + ≈85). Cyber charters are out of scope for v1 (they serve students statewide; attribution to Philly is conceptually fuzzy). They're addable as a tagged subset in v2.
- Outcomes: PSSA grades 3–8 ELA & Math proficiency, Keystone HS subjects (Algebra I, Literature, Biology), four-year graduation rate, chronic absenteeism. Survey climate via the Philly School Experience Survey (PSES).
- Geography taxonomy: SDP Learning Network (replaces NYC's community-district concept), Philly City Council district, neighborhood (Census tract aggregations from OpenDataPhilly), school type, admission category, grade band.
- Methodology: lift KX's spec verbatim — peer groups KNN(K=40) with hard filters on grade band + admission category, soft demographic distance; residual-z outliers (WLS on the spec's covariate set); comparability regimes for PSSA test-version changes.
- Out of scope for v1: statewide comparisons (Philly vs. suburban PA), per-pupil funding (same gap as NYC — patchy data), principal-tenure analytics (same gap).
3. Decisions (settled 2026-06-03)
All seven open decisions resolved. Recording with rationale so the reasoning is recoverable later.
| # | Decision | Resolution | Notes |
|---|---|---|---|
| O.1 | Same repo vs new repo | Same repo (multi-city namespace). Repo also renamed nyc-edu-data → edu-data to reflect multi-city scope. | GitHub auto-redirects old URLs ~6 months. Vercel deploy wiring (installation ID, not URL) survives the rename. Philly code lives under docs/cities/philly/, pipeline_philly/, data/cities/philly/, and philly/* branches. NYC code paths stay single-tenant until shared infrastructure is genuinely needed. |
| O.2 | Charter inclusion model | (a) — one universe, tagged. | Matches PDE's data shape (district + charter on same grain) and NYC's posture. school_type enum follows PDE's 5-value taxonomy (regular/charter/compctc/cyber/specialed) per findings.md §F.5; is_renaissance is a derived boolean. |
| O.3 | SDP's SPREE role | (c) — both. Cross-referenced ranking and (iii-a) spot-check oracle. | Mirrors NYC's posture with the School Quality Snapshot. Same-publisher caveat applies (presentation cross-reference, not independent oracle). Independent (iii-b) oracle is Future Ready PA Index, available day one. |
| O.4 | PSSA test-version regimes | Two regime breaks: 2014-15 (PA Core redesign) and 2022-23 (post-COVID recalibration). Standardized z within regime; raw values across. | Same comparability posture as NYC's 2022-23 handling. Encoded in comparability.yaml during P3. |
| O.5 | Keystone aggregation rule | Latest-attempt, all-students, banded by school grade band. | Matches PDE's published convention. Encoded in outcomes.yaml. |
| O.6 | PSES survey rollup scope | Teacher + student as first-class rollups; parent + principal + support-staff as school-profile detail. Loader still ingests all 5 respondent groups into survey_responses. | Avoids UX bloat from 5 top-line survey metrics; mirrors NYC's two-first-class posture. |
| O.7 | PVAAS growth as first-class v1 indicator | Yes — include in v1. | Future Ready exposes PVAAS growth per subject × subgroup (per findings.md §F.2). NYC didn't have this; status-vs-growth methodology question is settled here by data availability. Metric naming: pvaas_growth_*. |
| O.8 | Actual vs Acct population cut for SDP PSSA | Acct as canonical (matches SDP's published SPREE composite). Loader ingests both files; the primary metric value comes from *_Acct_*.csv; a parallel <metric_key>_actual exposes the all-tested cut for transparency. A per-school "Acct vs Actual" diff report runs at ingest time as an additional reconciliation gate (analogous to a population-cut variant of the (ii) base case). | Same gap NYC has — Philly just publishes both cuts natively, so we don't have to reverse-engineer the accountability cohort. See 05_validation_spec.md §"Acct vs Actual" for the validation posture. |
4. Inheritance from NYC build
The Philly build reuses, without modification:
- Methodology spec (
docs/design/nyc-school-outcomes-spec.md) — engine, peer-group construction, residual-z math, comparability handling. - Reference scaffold (
docs/design/reference-scaffold/) —pipeline/analysis/engine.py,outliers.py,trends.py,verify/{checks,reconcile}.py, configs. - Validation taxonomy (
docs/design/05_validation_spec.md,verify/METHODOLOGY.md) — (i)–(iv) definitions. - Front-end shape — Outliers / Movers / Stories / school profiles, with the same direction-adjusted percentile semantics, peer-group toggles, and recipes infrastructure.
- Contribution workflow — branch-per-capability, additive + feature-flagged, PR linked to gap analysis and spec.
What is new and Philly-specific:
- Source connectors (Philly publishes via OpenDataPhilly Socrata + Future Ready PA Index Excel downloads + PDE bulk files; no NYCDOE InfoHub equivalent).
- Geography taxonomy (Learning Networks instead of community districts).
- The eight known story lines (charter-sector comparison, Mastery/Renaissance trajectory, school-closure retrospective on Hite's 2013 closures, etc.) replace NYC's Renewal / Small Schools / D15 stories.
5. Out-of-band: what this branch does NOT include
- Any ingested Philadelphia data — not even sample rows. Until the open decisions land, the source connectors are unwritten.
- Any code change to NYC paths. Everything is under
docs/cities/philly/. - A decision about repo split (O.1). The plan documents are written so they apply equally to "same repo, new namespace" and "new repo, copy-then-modify."
6. Next step
Decisions settled 2026-06-03; work proceeds from 03_integration_plan.md.
First-fetch (P1 prelim) shipped on philly/first-fetch — two Future Ready
sources resolved. Next batch: PSES + SPREE + OpenDataPhilly discovery, then
P0 scaffolding under same-repo conventions.