Retrospectives

Post-ship engineering writeups. Each entry covers one iteration: what we tried, what failed, what we learned, what we'd do differently. Audience is the future engineer (often us) debugging the next iteration.

The blog (/research) carries lighter narrative writeups for a general audience. These articles are the deeper-dive companion — pin-down-the-failure-mode level, with enough trace + numbers + config diffs to be useful in three months.

Index

• v0.4.0 ablation campaign — the verdict-smoke meta-bug and what we shipped instead — five training divergencesdivergenceA training failure where loss descends through warmup, plateaus low for a while, then climbs catastrophically back to its starting magnitude — the model unlearns everything despite no obvious component failure., one decoderdecoderIn a transformer encoder-decoder model, the part that produces output sequences. Mailwoman's classifier is encoder-only (no decoder); the 'CRF decoder' is a different thing — a structured-prediction layer that picks the best label sequence from the encoder's outputs. sidecar, three deferred work areas. 2026-05-23.
• v0.6.x cycle retrospective + v0.7 plan — three corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus.-recipe iterations couldn't find a stable configuration; the deeper finding (calibration crisis + wrong release metric + postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses. fragmentation) reframes v0.7. 2026-05-29.
• v0.7–v0.8: the neural parser vs the rules baseline (two scoreboards) — why neural scores 20.7% on our PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.-lineage harness yet beats PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. 97.3% vs 95.8% on real addresses; the three-arenaarenaA standardized test set probing one capability: libpostal (clean canonical), perturb (noisy and degraded), postal (edge formats). Each arena answers a different question about where rule vs neural wins. decomposition; the MLM pre-trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. negative result; forward plan ranked (streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level geometry first). 2026-05-31.