How it works
A coordinator points the tool at a folder of exports. Adapters recognise each file, read it into a documented package, and a dashboard is written as one HTML file. A verification tab shows that every value reconciles, and a reviewer signs off.
1. Adapters read what the program can already export
Each source type has its own adapter. An adapter first fingerprints a file, reading only its headers or first page, and either recognises the layout or says plainly what it looked for and what it found instead. Only a recognised file is read. Adapters are independent: adding one never changes another.
| Source | What it reads | Status |
|---|---|---|
| New Innovations | Evaluation results by resident and rotation, milestone ratings, conference attendance, duty-hour summaries, case logs, scholarly activity. Column names vary by institution; the adapter maps by header and reports what it could not map. | Phase 0 fixes the list |
| ACGME surveys | Resident, faculty and well-being survey reports, multi-year, raw or already cleaned by SurveyDeID. | Parser exists |
| Exams | PRITE program and resident reports; board pass rates by form or CSV. Other specialties add their own in-training exam as data. | Phase 1 |
| Internal surveys | Qualtrics, Microsoft Forms, Google Forms and REDCap exports. Free text never reaches a PEC dashboard without de-identification and a human release. | Phase 2 |
| Operational data | Duty hours, attrition, recruitment and match figures, scholarly activity, from CSV or a short form. | Phase 2 |
| Any CSV you choose | A mapping screen: name the source, label each column, pick a display and a direction. The mapping is saved and reused next year. This is what makes "any private data source" true without new code. | Phase 2 |
Flag, do not infer. Conflicts, gaps and unparsable values are listed for the coordinator. Nothing is interpolated or silently corrected.
2. Everything lands in one documented package
All ingest ends in a folder of six JSON files on the program's disk, validated against one versioned schema. Dashboards only render it. Whether the reading is done by a Python program or inside a browser is a packaging choice made after the requirements are known.
| File | Holds |
|---|---|
manifest.json | Schema version, which tool wrote it, an opaque program id, and whether the folder is safe to share |
dataset.json | Records: one row per observation, exactly as the source states it, each with a pointer to its file, sheet or page, row or field |
analytics.json | Values a dashboard may show: which records they came from, by which named method, with the count of people behind them and whether the cell was too small to show |
provenance.json | Every source file with its hash and the layout it was recognised as, so format drift is visible |
annotations.json | Committee input that survives a rebuild: action items carried forward, notes, decisions, sign-offs |
issues.json | What could not be mapped, parsed or reconciled |
A specialty is data, not code: milestone subcompetency names, in-training exam names and survey benchmarks live in a specialty pack. Psychiatry ships first; a second specialty is added by writing files.
3. The dashboard is one file
No server, no external requests. It opens from a shared drive in any modern browser. Its own security policy forbids every connection, and the build fails if the file references a URL. Tabs are modules; enabling or removing one is a configuration change. The verification and sign-off tabs cannot be removed.
PEC dashboard
Overview with flags · ACGME survey by domain and year against the specialty benchmark · exams · internal evaluations · operations · custom sources · action plan · verification · about the data.
Program-level. Any group smaller than the program's threshold (default five) shows as suppressed, not as a number. Counts sit beside every percentage; the direction of "better" beside every score.
CCC dashboard
Cohort grid by PGY year · per-resident milestone trajectory against prior periods and the peer band · evaluations by rotation and evaluator role · exam trend · flags with evidence · meeting agenda · post-meeting ADS checklist.
Names residents by design. Says so on every screen and in the file name. Never the input to an AI step. Comments are shown verbatim with their source; the tool never summarises them.
4. Verification and sign-off ship in every dashboard
The verification tab walks every displayed value back to its records and every record to its source file, and shows the count matched and the mismatches. A named reviewer records a sign-off with a date. The sign-off is bound to the exact bytes of the analytics: rebuild the package and the dashboard shows an unverified banner until someone verifies and signs again.
The same reconciliation is the automated acceptance test for every adapter. A format change at the ACGME or in New Innovations shows up as a failed test, not as a silently wrong number.
5. AI, if at all, on de-identified text only
The dashboards are complete without any model. Optionally, the PEC generator exports a committee brief: aggregate, suppressed, de-identified, checked twice. A program then runs our skills in its own institution-approved AI account to draft the APE narrative, a CCC agenda or a citation response. We never see the data. CCC data never enters a brief.