Every finding the scorecard surfaces carries a one-line fix. This is where those fixes grow into short, practical how-tos, keyed by the validator notice code (or the scorecard's own code for metrics the validator does not cover).
It is the most durable thing the project builds. A finding tells an agency what is wrong; a fix page tells them which setting to change in the tool they actually use. The roadmap (docs/roadmap.md) calls this out as a cross-cutting piece worth starting early and never finishing, because it gets better with every agency conversation.
One file per code, named for the code: docs/fixes/<code>.md. Each page has the
same short structure so a CSM can read it aloud on a call:
-
YAML front matter with the original publication date and latest substantive review date:
--- date_published: "YYYY-MM-DD" date_modified: "YYYY-MM-DD" ---
-
What this means in plain language.
-
Why it matters to a rider or to the agency.
-
How to fix it, with the common scheduling tools named where the setting differs between them.
-
How long it usually takes.
Keep date_published fixed. Update date_modified only after a substantive
content review or change, not for a routine site rebuild or formatting-only edit.
The frontend can deep-link to these pages from a finding by its code, so the "Fix" line on a scorecard becomes a link to the full walkthrough.
Each page also links to the finding's canonical rule: the matching
MobilityData gtfs-validator notice, a GTFS Best Practice, or the GTFS Schedule
reference. That mapping is data, not prose: it lives in
pipeline/src/scorecard_pipeline/rule_links.py, and tests/test_rule_links.py
asserts every page here has an entry and vice versa, so adding a page without a
rule mapping fails CI. See ADR 0024.
These cover the codes seen across the tracked agencies, grouped by the scorecard
category that surfaces them. This list is hand-maintained (nothing in CI checks
it against the actual page set, only against RULE_LINKS; see ADR 0024), so
add a page's link here in the same change that adds the page.
Correctness (validator notices):
big_gap_in_serviceequal_shape_distance_same_coordinatesexpired_calendarfast_travel_between_consecutive_stopsfast_travel_between_far_stopsfeed_expiration_date7_daysfeed_expiration_date30_daysinvalid_currency_amountmissing_feed_contact_email_and_urlmissing_recommended_fieldmissing_recommended_filemissing_required_columnmissing_timepoint_valuemixed_case_recommended_fieldroute_color_contrastservice_has_no_active_day_of_the_weekservice_window_outside_feed_periodstop_too_far_from_shapestop_too_far_from_shape_using_user_distancestop_without_stop_timetrip_coverage_not_active_for_next7_daystrip_distance_exceeds_shape_distance_below_thresholdunknown_columnunknown_fileunused_shape
Freshness (scorecard codes):
Rider experience completeness (scorecard codes):
scorecard_flex_no_booking_rulesscorecard_missing_headsignsscorecard_no_fare_datascorecard_no_feed_contactscorecard_station_no_pathwaysscorecard_stop_names_all_capsscorecard_wheelchair_accessible_unknownscorecard_wheelchair_boarding_unknown
Realtime quality (scorecard codes):
scorecard_rt_service_alerts_unreachablescorecard_rt_trip_coveragescorecard_rt_trip_updates_unreachablescorecard_rt_vehicle_positions_unreachable
The backlog is the rest of the MobilityData notice taxonomy: a code gets a page as soon as it shows up in a tracked agency's findings.