Writing series: the story of the repo, chapter by chapter

[baz8080]

The third of the family's series, after uisce#43 and esb#30, in the same voice and to the same rules: a chapter-by-chapter account of how this repository went from a script polling Irish Rail's service-message feed on a Pi to a site that says what a lift outage did to step-free access. Written for an intelligent non-programmer, with a concept box for every hard idea and a worked example with real numbers for every concept. Prose and diagrams only; nothing under writing/ is imported by the package and CI is unaffected.

11 posts, ~21,500 words. Shorter than esb's 12 / 24,500 and much shorter than uisce's 18 / 32,600, because the repo is three weeks old, it inherited its collector architecture rather than deriving it, and the shared-UI story has been told twice already.

The shape is the argument

This repo looked like the easiest of the three - one endpoint, one flat list, no geography, no Census, no regulator - and the difficulty arrived at the end and was not engineering. So the series is deliberately back-loaded. Chapters 01 to 05 are the site anyone would expect. Chapters 06 to 09 are 8,600 words, 40% of the series, on a problem neither sibling has:

• 06 The data Ireland does not have. Every source checked and empty: no pathways.txt in any of the three NTA archives, wheelchair_boarding column-absent rather than unpopulated, AccessArea null on all 152 NaPTAN rail stops, PTIMS bus, the NTA API bus, getAllStationsXML inventory-only, the lifts-and-escalators alerts page struck. NeTEx and SIRI-FM would carry exactly this and Ireland publishes neither. Then the reason: EU 2017/1926 obliges publishing the listed data types "provided they exist in digital machine-readable format", so the duty is to publish what you hold, and the absence is lawful with no process that closes it. Then what it costs: five mapping products read the three GTFS fields that are missing, so none can offer wheelchair routing on Irish Rail. Ends on the unintended consequence, that lifts-data/stations/ appears to be the only versioned machine-readable record of Irish rail station access that exists.
• 07 "and" is a sequence, not a choice. Hazelhatch, the boilerplate that invents lifts at three stations, the 61-station check, why the model parses no connectives at all, specific-beats-general, an inference that expires to unknown and not lost, and the six unknowns that are each a real contradiction between two hand-written sources.
• 08 The same bug, three times. Three of the second review's findings were the first review's findings reappearing in the fixes, and underneath them one shape: a predicate over the wrong quantity, passing vacuously. Audited for, and found twice more in the collector (Refuse a rebuild that recovered nothing, and time the alert window from delivery #34). Plus OSM carried, measured, removed.
• 09 What one letter cannot say. The open issues as reasoning rather than a backlog: The grade and the station page disagree about escalators #32's Pearse F on an escalator alone, Model the entrance leg, and say who an escalator outage affected #33's entrance leg, Say which platform was still step-free when a lift was out #31's 32-of-57, Lift and escalator bars are not disambiguated in the bar views #28.

Chapter 03 is the short one on purpose, and says so in its first line.

The series' own mandate

esb's rule is two-way. This one is three-way, because on the questions that matter all three sites landed differently and none of the splits is taste. Every fork is stated as (what uisce does, what esb does, what this does, and the fact about this feed that forced it). The four that anchor chapters:

	uisce	esb	lifts	forced by
The operator's start	publication time, re-stamped; every duration a floor	back-dated by hours, immutable, measured from	back-dated by months, shown, colours nothing	Rush and Lusk dated 451.6 days before its first sighting
How big an event is	population in a 500 m circle	ESB's own customer count	there is no size	the feed carries no count of anything
What anchors the grade	own thresholds on person-hours	ESB's published 4-hour / 95% aim	own bands, counted in days	the PRM TSI sets a duty to hold a policy, not a percentage
What knocks the grade	KNOCK_CATS, binary	planned works excluded, storms kept and said	works excused a week then counted; escalators knock, and that is open	nobody excluded anything on our behalf

The last row is the spine of the back half, and the closing carries a ten-row version plus the "identical column" of conventions all three share.

What is in it

• writing/chapters/ - 11 posts, each standalone, 1,200 to 2,400 words, with read time, "where we are", 14 concept boxes, worked examples and sourced notes.
• writing/diagrams/ - three hand-written SVGs (the 451-day claim against the watched window; the two readings of Hazelhatch's sentence; what would carry the data against what Ireland publishes), plus one mermaid flow in chapter 01. All three rendered and checked.
• writing/figures.md - every number quoted, with source and date.
• writing/README.md, outline.md, PROGRESS.md - style guide, chapter briefs, and the ledger.

Reviewer notes

• Figures are re-measured, not lifted. Unlike the esb series this one had the corpus to hand, so ../lifts-data was pulled to 999922e, rebuilt, and the site build and lift_access report run against it. figures.md separates "measured 31 Aug 2026" rows from "quoted at the date they were measured" rows, and says where a number has since moved (availability 70 to 66 to 67; Pearse 22% to 21% to 20%; Midleton 19 days to 24).
• One figure is flagged as rule-sensitive. "32 of 57 stations name a platform reached without a lift" is recorded from notes/station-access.md rather than re-derived: a quick re-derivation with a narrower rule gives 27, so the definition differs, not the data. Worth pinning down when Say which platform was still step-free when a lift was out #31 is built, since that number gets published then. Noted in both figures.md and PROGRESS.md.
• Two corrections to the record, both from measuring. Chapter 02's Rush and Lusk story: the notice was present at the very first poll, so its 451 days precede collection entirely rather than being watched-and-absent. Docklands and Hazelhatch are the watched-and-absent cases and carry that half of the argument now.
• Punctuation. This repo's rule is stricter than esb's - scripts/no-em-dash.sh greps tracked files for en dashes too - so writing/ is checked by the repo the moment it is committed, and numeric ranges are written out. Clean.
• Chapter 09 is the most perishable thing here, and PROGRESS.md says so: The grade and the station page disagree about escalators #32's recommended option would change every figure in chapters 05 and 09 the day it lands.
• The AI-assisted process is named once, in 00, with the trailer counts from the log.
• Draft: for a read-through, not a merge. Diagram polish, the continuity/review pass and a root README pointer are listed as later passes in PROGRESS.md, as both sibling series did.

287 tests pass with LIFT_STATUS_DATA_DIR set, ruff is clean and no-em-dash.sh is clean, though none of them is exercised by this branch: it adds no code.

🤖 Generated with Claude Code

[baz8080]

Update 4 Sep 2026 - chapters 10 to 12, and the closing renumbered

main is merged in. Session 0 flagged chapter 09 as the most perishable thing in the series, and it was right within four days: all four issues it described as open closed between 1 and 3 September, over nine merged pull requests.

The series is now 14 posts, ~29,400 words (was 11 / 21,500).

Chapter 09 is kept, not rewritten

It states the argument as it stood on 31 August, with a dated note at the top, forward pointers where a decision has since gone a particular way, and a closing section saying what actually happened next. Rewriting it to match today would have thrown away the thing that made the four days cheap, which is that the arguments were written out with the numbers in them.

The order it closed in is the story, and I did not predict it: #28, dismissed in chapter 09 as "the small one", was the blocker for #32. The argument that had kept escalators in the grade was never about what a grade should measure. It was that Connolly's row gave a reader no way to tell whose red cells those were. Reserving a 15px kind gutter on every row removed the argument.

The three new chapters

• 10 Two ways the page lied about time (Publish on the data landing, not on a cron that runs hours late #39, Record one listing row per stretch a notice was on the feed #42, Fix past month ongoing count to include stations listed when month ended #44, 2,192 w). The banner read "collection has stopped" when the build had: GitHub's scheduled runs were landing four to ten hours late every day, so the site builds on the data landing now and the crons are a fallback, pushes went six-hourly and STALE_AFTER followed 16 h to 10 h. Then the worse one: a notice that vanished and came back unchanged was published as never having left, because the unique identity key left nowhere to put the second appearance. Portlaoise as one 16-day outage rather than two short ones a fortnight apart. Boxes: the age on the page is the age of the data, not of the build; a test that exercises the easy half (the existing test gave the returning notice a corrected start, so it only ever ran the path where the bug cannot occur).
• 11 The grade narrows to lifts (Say which bar is lifts and which is escalators #38, Grade on lift availability, and let an escalator notice paint its bar alone #43, 1,812 w). The gutter, then escalators off the letter, and the careful refusal of issue The grade and the station page disagree about escalators #32's own wording: the key says "Lift availability" and not "step-free availability", because the grade counts notices and a quarter of the access verdicts are unknown. Boxes: a conditional column is a misalignment; a rule with no instance, written down and guarded.
• 12 Both legs, and who was on the stairs (Add note when another platform kept step-free access (issue #31) #37, Read a notice against the leg it names, and say who an escalator outage affected #45, 2,668 w). The kept-platform note, leg detection from the notice's own text, the entrance leg read against ticketOfficeAccess, the escalator sentence that names who lost a way up, the overlap guard, and the golden file born of two fixes that were themselves regressions. It ends on notes/station-access.md § How reliable this is, honestly, which is the most valuable thing to come out of that day and is now a concept box: what the code's own history says about the code.

Reviewer notes on this update

• Figures re-measured against ../lifts-data at its 4 September state. The 31 August measurement is kept as its own block in figures.md, because chapters 00 to 09 quote it and say so, and because several of its rows were not merely stale but wrong in a way chapter 10 explains: Portlaoise's 29%, Thurles' 25% and Clondalkin's grade all included a fortnight the notice was not on the feed.
• Chapters 00, 02, 03, 05 and 07 gained forward pointers and current figures. Chapter 05's decision to count escalators is now explicitly the thing chapter 11 undoes, with the note that what changed was not the argument but the row.
• The closing is renumbered 10 to 13 and trimmed back under the series' own 3,000-word ceiling. Its three-way table's "what knocks the grade" row now reads escalators show on their own bar and do not knock, which matches uisce's binary KNOCK_CATS rather than merely citing it as a precedent.
• Glossary is 20 concept boxes, up from 14. Read times recalculated against actual word counts.
• PROGRESS.md names the next perishable thing: chapter 12's entrance leg is machinery with no live case. No entrance-leg lift notice has ever been listed, and the day one is, both the chapter and the reliability note need a paragraph.
• The three SVGs needed no changes.

390 tests pass with LIFT_STATUS_DATA_DIR set, ruff check and scripts/no-em-dash.sh clean. Still touches writing/ only.

[baz8080]

Update 12 Sep 2026 - chapters 13 to 16, and the closing split

main is merged in, over PRs #46 to #54. The series is now 19 posts, ~37,200 words (was 14 / 29,400).

Two settled sections reversed in one week, both narrated rather than edited

This is now the pattern across three sessions and it is the most distinctive thing about this series, so PROGRESS.md states it as the standing habit: date the chapter, leave it standing, write the correction as a later chapter.

• Ch 14 corrects ch 12. Chapter 12 described the access golden file's cost as a deliberate trade-off, the monthly review made mandatory. It was also something else: the fixture pinned outputs but re-derived them from whatever lifts-data held when CI ran, so it failed on other repositories' schedules. Rush and Lusk's body flipped overnight on 8 September and a build went red on a merge that could not have caused it. Underneath it was a sentence written confidently into the notes: "the logs are append-only and that can only mean a bad checkout." The logs are. messages is not, because identity excludes the body, so a reword overwrites text_raw in place. There is a second irony the chapter keeps: the version built to avoid being "silently off from the first refresh nobody regenerated after" was silently off for anybody without a data checkout.
• Ch 15 corrects ch 06, and is the big one. notes/accessible-routes.md had ruled out hand-curation since 29 August because a hand-curated file has "no provenance, no refresh and no audit". Those are three properties, and properties can be built. The chapter's concept box is the objection is a specification: writing a rejection out in full as three named defects is what let it be read later as a list of requirements rather than a verdict. It ends on the turn the whole series has been building to without knowing it - a gtfs command exporting the very pathways.txt chapter 06 established Ireland does not publish.

The other two new chapters

• 13 What a reader can take away (Say which stations are out now, publish feeds and a CSV, and warn about what the page cannot show #49, Align the "Lift out" tag to the right of the name column #50): the "Lift out" tag, Atom feeds, a CSV, a link back to the quoted page, and two tripwires that are not for visitors at all - unclassified_mentions and thin_days. Boxes: a feed entry for something still happening (dated to the appearance, then moved to the close, so a subscriber sees the outage twice and the second showing is the completion signal); a tripwire for a silent drop.
• 16 A fourth site, and two bugs found sideways (Record what the delays site cost this repository, and the one trap it found #54, issues Kishoge station-facts record is keyed by name, not location code #52/"planned maintenance" is not "planned works", so Salthill and Monkstown is graded as a fault #53): the boundary written down, the location-codes trap (288 of 497 non-lift notices lose their codes partway, zero lift notices ever have), and two bugs found by pointing a different tool at the same data. Box: a second reader of the same data is a test you did not write - one disagreement in 416 notices is a finding no amount of staring at the regular expression would produce.

Structural

• The closing is split into 17a and 17b. It had reached 3,523 words, past the series' own 3,000 ceiling, so it follows the sibling convention for an over-length chapter: 17a is the account (figures, the two lists, the three-way table, the settled decisions), 17b is the moral and the glossary.
• New chapters take 13 to 16 rather than 14 to 17, so no number is skipped.
• Glossary is 27 concept boxes, up from 20. Read times recalculated.

Figures

Re-measured against ../lifts-data at its 12 September state. figures.md now keeps three dated blocks, because chapters 00 to 09 quote the 31 August corpus and 10 to 12 quote the 4 September one, and both say so.

One number is worth calling out on its own. The unknown verdict share is going the wrong way: 6 of 24 on 31 August, 7 of 30 on 4 September, 14 of 45 now. The corpus keeps reaching stations whose pages are thinner than the ones it started with, which is exactly what chapter 12's reliability section meant by the page's own error rate being the ceiling. That trend is the strongest argument in the series for chapter 15's survey, and both the intro and 17a now say so.

Still open

PROGRESS.md names what will date first: chapter 15's graph is a schema and a five-station pilot the site does not read yet, and the day it does that chapter needs a successor rather than an edit. Issue #53 turns on what chapter 04's grace is for, so whatever is decided belongs beside that argument.

516 tests pass both with LIFT_STATUS_DATA_DIR set and unset, ruff check and scripts/no-em-dash.sh clean. Still touches writing/ only.

[baz8080]

Session 3: extended over #55 to #58 (24 Sep 2026)

Two chapters added, and the closing renumbered 19a / 19b so no number is skipped. Now 21 posts, ~42,200 words, 31 concept boxes.

• 17. The same thing, said differently (Fix Kishoge's station code join (issue #52) #55, Treat "planned maintenance" and "engineering works" as planned works #56). Both of chapter 16's bugs close, and neither the way its issue proposed. "planned maintenance" is not "planned works", so Salthill and Monkstown is graded as a fault #53 was answered as vocabulary, and by chapter 04's own account of what the grace is for, that is the purpose answer too. Salthill and Monkstown's September goes from E 66% to C 91%. Kishoge's page puts the name in the code field. The issue's "missing, falls back" diagnosis was wrong and chapter 16 repeated it. The fix is a one-entry table, and nothing guards the next one.
• 18. The one code a rebuild cannot undo (Say what a comment has to record to earn its place #57, Review the collector: the raw line no longer waits on the database #58). The collector's first whole-file review. It corrects two sentences of chapter 01: the raw line was written inside the block that opened the database, and sort -u deduplicates by sorting, which reorders lines, so replay now sorts by fetch time.

One finding no PR mentions. August's national figure moved from 76% to 75% after August ended. Rebuilding the corpus cut at 12 September with today's code isolates it to one station-month. Tullamore's planned-works notice came back on 16 September, the pooled grace crossed a week on the 19th, and its August went from A 100% to D 83%, with nothing on the page marking the month as revised. Chapter 17 narrates it as a finding, not a decision. No issue exists for it yet.

Forward pointers added to 01, 10 and 16, which are otherwise left as written. The unknown verdict share is still climbing: 6/24, 7/30, 14/45, now 23/58. Still writing/ only; no-em-dash.sh clean; 526 tests pass.

🤖 Generated with Claude Code