code.dblock.org | tech blog

Porting My 1996 Pascal/Delphi Calculator to Rust (CLI + MCP)

2026-09-24T00:00:00+00:00

In his Rails World 2026 keynote DHH talks about one-shot apps built almost instantly with an agent as part of Omarchy. His canonical example is Omacalc, a dead simple calculator. It’s a good demo and not a hard problem. Let’s take it further and rewrite a more advanced calculator in Rust that we can also run as an MCP server, so an AI coding agent can outsource arithmetic to it instead of hallucinating a square root.

In 1994 I wrote an expression evaluator for a lab assignment. It grew into Expression Calculator, a shareware Windows app I sold through a company I co-founded, Vestris Inc. In 1997 it got pressed onto a CD-ROM and sold 3,000 copies in Germany under the name Global Calculator. I made money and users wrote fan mail. This week, Copilot and I ported its Pascal/Delphi core to Rust as excalc-rs (crates.io), a CLI and MCP server, in under 24 hours.

Both the port and the original are mathematical beasts. They can:

Chain 12 comparison and logical/bitwise operators, and 12 arithmetic operators with correct precedence
Fit 8 general/rounding functions and 7 statistics functions (mean, variance, standard deviation)
Evaluate 36 standard math functions: trig, inverse trig, and hyperbolic variants, both in radians and degrees
Answer 17 number theory questions: GCD/LCM, Fibonacci, primality, Mersenne and perfect numbers, Euler’s totient
Run 18 financial functions: NPV, IRR, loan payments, present/future value, depreciation schedules
Numerically integrate anything via 7 quadrature methods (trapezoid, Simpson, Gaussian, and more)
Compute 21 advanced/special functions: the Gamma and Beta functions, elliptic integrals, Fresnel integrals, the error function, dilogarithm, Dawson’s integral, sine and cosine integrals

Let’s verify that Euler’s Gamma function is the continuous extension of the factorial (Γ(n) = (n-1)!), and comes back essentially zero (floating-point noise from numeric integration):

calc 'gamma(10) - 9!'
# 0.000000054249539971351624

Γ(10) equals 9! to 7 decimal places, computed via numeric integration rather than table lookup.

Check out the docs/.

The 1996 Original

The original was years of work. The Pascal source code is on GitHub, open-sourced in 2009 once Vestris wound down in its original British Virgin Islands offshore incarnation. The core common/MCalc.pas is a 4,036 lines long evaluator. The full Windows app, UI included, is 10,339 lines of Pascal across the repo, backed by a 189-page user’s guide I apparently wrote it in XEmacs and typeset with SgmlTools. I have no memory of most of this code or the math behind it. It’s 30 years old. I was 20.

The 2026 Port

The Rust port’s git history is one Copilot CLI session, 145 turns, spread over 24 hours:

2026-09-23 20:46  Initial scaffold: core arithmetic engine, standard math, statistics
2026-09-23 20:47  Add CI: build/test on Linux/macOS/Windows, fmt + clippy checks
2026-09-23 20:53  Release v0.1.0
2026-09-23 21:14  Add test coverage reporting to CI via cargo-llvm-cov and Coveralls
2026-09-23 21:38  Add MCP server exposing evaluate as a stdio tool
2026-09-23 22:29  Implement general/rounding functions (abs, frac, intg, round, trunc, ceil, floor, random)
2026-09-23 22:53  Add comparison and logical/bitwise operators
2026-09-23 23:16  Implement advanced / special functions
2026-09-23 23:32  Implement financial functions
2026-09-23 23:43  Implement general-purpose numeric integration
2026-09-24 06:07  Add short descriptions to every README example
2026-09-24 06:27  Implement variable assignment (:=)
2026-09-24 07:24  Add degree/radian conversion and degree-native trig functions
2026-09-24 07:59  Add Homebrew formula and CI validation
2026-09-24 08:09  Add Windows MSI installer via cargo-wix
2026-09-24 08:22  Release v0.2.0

The first v0.1.0 cut that did basic math shipped 7 minutes after the initial scaffold. I slept for 6 hours and went out on a run. The complete port totaled 59 commits, 5,060 lines of Rust, 217 tests, and a v0.2.0 published to crates.io, tapped on Homebrew, and shipped as a Windows MSI, by the morning.

The token bill for the port was 732 API calls across the session, ~83 million input tokens processed (~80 million of those were cache reads), and about 262,000 output tokens at a rough napkin math cost estimate of $50. Pretty great ROI given that I sold the original Expression Calculator for $25 a copy!

Some Interesting Math

Much of the advanced math in the calculator was taught by professors Ernst Hairer and Gerhard Wanner from their book, Analysis by Its History. I took the course as an undergrad.

For example, the book spends real time on elliptic integrals, which get their name from the problem of computing the arc length of an ellipse, a problem with no elementary closed form. excalc-rs implements ellipticE, the incomplete elliptic integral of the second kind, exactly as the original Pascal did as a numeric integration, not a series approximation:

calc "4 * 5 * ellipticE(0.8)"
# 25.52699886339813

That’s the circumference of an ellipse with semi-major axis 5 and semi-minor axis 3 (eccentricity sqrt(1 - 3^2/5^2) = 0.8), a number with no closed form, computed by adaptive quadrature under the hood, the same way ci, chi, erf, and a dozen other special functions are as thin wrappers around a shared int(expression, variable, lowerBound, upperBound, tolerance) engine. See docs/functions/advanced.md.

Try It Out

cargo install excalc
calc "sqrt(16) + sin(pi/2)"
# 5

Use brew tap dblock/excalc-rs https://github.com/dblock/excalc-rs and brew install excalc on macOS/Linux, or grab the MSI from the latest release on Windows.

Using AI Effectively in Technical Writing

2026-09-23T00:00:00+00:00

I write a lot, and I use AI a lot. But AI does not write my blog posts. Mostly.

AI is useful for making some of my writing less tedious. Recently, I asked GitHub Copilot CLI to read a few dozen posts from this blog and derive a VOICE.md to assist my writing. The result is now checked into this repo and linked from AGENTS.md, so any AI agent working here gets the same reminder: this blog is authored by me, not by AI and the agent’s job is to help me rather than pretend to be me.

The useful and interesting part of VOICE.md was how it captured my weirdly specific patterns.

Start with a real story, failure, command, bug, or piece of data.
Say the opinion early.
Provide examples, pull requests, commands, screenshots, numbers, links.
Admit mistakes.
Let short posts stay short.
End quickly, use Russian jokes or a link.

Technical writing is just like coding, but do not attempt to fully automate it. Be picky about words, punctuation, examples, and whether a sentence actually sounds like something you would say. Use AI to produce a flow or even a draft, to collect patterns, suggest structure, and do the boring, time-consuming work around technical reproductions or samples. When a post needs the same example in Ruby, Python, JavaScript, Go, Rust, PHP, C#, Java, Elixir, Swift, Objective-C, and Dart, have an agent generate the first pass then verify, fix, and explain the interesting parts.

Using AI Effectively in Technical Writing was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 23, 2026.

Serving Markdown for AI Agents, Now as a Jekyll Plugin

2026-09-19T00:00:00+00:00

Back in January I wrote Serving Markdown for AI Agents: for every page on this blog, there’s also a .md version at the same URL, discoverable via a <link rel="alternate" type="text/markdown"> tag, so AI agents can fetch clean Markdown instead of parsing HTML. It also made me $360, via referral conversions an AI agent apparently generated after reading the clean Markdown version of a post.

That worked, but it lived in this repo as a one-off script, _scripts/render_markdown.rb, wired into the GitHub Actions deploy workflow (needed since GitHub Pages’ native build only allows a small allowlist of plugins, which jekyll-md isn’t on), with the <link> tags added by hand via Liquid and a markdown_url front matter field on every page.

I’ve since extracted all of it into jekyll-md, a proper Jekyll plugin. It does the same thing - converts each page’s fully rendered HTML output to Markdown and injects the discovery <link> tag - but as a Jekyll::Generator and Jekyll::Hooks, with no external script or per-page front matter required.

What Changed

Add the gem and enable the plugin:

# Gemfile
gem 'jekyll-md'

# _config.yml
plugins:
  - jekyll-md

If you don’t configure anything else, jekyll-md looks for <main> or [role="main"] before falling back to the whole <body>, since that’s the closest thing HTML has to a content/chrome convention. You can also configure a CSS selector to convert from, e.g. md: selector: "#markdown-content", and other options - see the README for the full list.

What About llms.txt?

There’s a related convention, llms.txt, a single root-level file that’s supposed to give an AI agent a curated map of a site. I considered adding llms.txt generation to jekyll-md, then didn’t. The spec is explicit that the file should “stay small enough to fit in context” and contrasts itself with sitemap.xml, which it calls out for being too large and unfiltered to be useful. A plugin walking every page and dumping it into llms.txt - which is what some similar plugins do by default - just recreates the sitemap problem in Markdown instead of solving it. This blog alone has almost 600 posts; nobody wants all of them in one file.

Instead, I wrote llms.txt by hand as a plain Jekyll page with Liquid front matter, listing a handful of pinned posts, the 10 most recent ones, and a few key pages, reusing this blog’s existing pinned: true front matter flag rather than inventing a new mechanism. You can see the result at code.dblock.org/llms.txt and the template that generates it.

In Meetings, Raise Hands Before Reading

2026-09-17T00:00:00+00:00

I spent five and a half years at AWS before moving (back) to Microsoft, where I work today. At Amazon, many meetings began with silent reading. Instead of presenting a document, the author gave everyone time to read it before the discussion started.

There was a small facilitation trick that made this work surprisingly well: when reading began, everyone raised a hand. When someone finished, they lowered it. The meeting started with all hands up and counted down to zero.

At Microsoft, I found the inverse practice: everyone began with their hands down and raised one when they finished. At the time of writing this, you’ll find me hard at work changing the culture of raised hands at Microsoft, one meeting at a time. Raise your hand as you start reading, lower it when you are done.

Both approaches appear to communicate the same information. They do not. Counting down is better than counting up.

TL;DR:

A raised hand shows who still needs time, which is the information the facilitator needs.
Counting down ends unambiguously at zero without counting participants.
A forgotten click makes the group wait instead of cutting off a reader.
The facilitator can see progress and check in when only one reader remains.
Reading ends with every hand down, so raising one can immediately mean “I want to speak.”

But first, why read during the meeting at all? Jeff Bezos explained the practice at Amazon. I really like this as it forces one to prepare for the meeting, gets everyone on the same page, and offers some of the smartest but quietest people an opportunity to comment on their own pace.

Back to the hands.

At Amazon, a raised hand meant “I still need time.” The signal described the state that mattered to the facilitator: these people were still reading. When the last hand went down, the group was ready. At Microsoft, a raised hand meant “I am done,” which was less actionable. The facilitator did not need to know who was done. They needed to know who still needed time.

With hands up at the start, the meeting counts down. At zero, begin the conversation.

When hands go up as people finish, the facilitator must count them and compare that number with the expected number of readers. Was it ten people or eleven? Did someone join late? Did someone leave? Is a person without a raised hand still reading or not participating? Counting up requires knowing the denominator. Counting down only requires reaching zero.

People forget to click buttons. At Amazon, someone who forgot to lower their hand caused the group to wait a little longer. The facilitator could ask whether they were done.

At Microsoft, someone who forgot to raise their hand was indistinguishable from someone who was still reading. Worse, if the facilitator miscounted the expected readers, they might begin the discussion while someone was still trying to finish the document.

The Amazon model’s failure mode was to give people more time. The Microsoft model could fail by cutting them off.

A decreasing number of hands makes the pace of the room obvious without interrupting the silence. If several hands are still up, the group needs more time. When one hand remains, the facilitator usually checks in with the last reader: “Do you need another minute?” The reader can ask for more time or say that they are ready, without polling the entire room.

This lets the facilitator adapt the reading period to the actual document and actual readers instead of guessing in advance or repeatedly asking, “How much more time do people need?”

At Amazon, people lowered their hands when done and moved on. The active signal belonged to the people who still needed something from the meeting: silence and time.

At Microsoft, finished readers accumulated raised hands and kept signaling a state that no longer required action. The display became increasingly busy while the useful information - who was still reading - remained represented by an absence.

The Amazon practice also created a clean transition from reading to discussion. By the time reading ended, every hand was down. Anyone could then raise a hand to signal that they wanted to speak.

The inverse practice left every finished reader’s hand raised at exactly the moment the conversation began. Everyone first had to lower their hand before the same gesture could mean “I want to speak.” If someone forgot, the facilitator could not tell whether it was a stale “I finished reading” signal or a new request to join the discussion. From the Systems Engineering perspective, good protocols reset their state before changing the meaning of a signal. Counting down naturally resets every hand to down, ready for the conversation.

Start with every hand raised. Lower yours when you are done. Begin the conversation at zero.

In Meetings, Raise Hands Before Reading was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 17, 2026.

Porting a Discord Bot to Microsoft Teams, Entirely With AI

2026-09-16T00:00:00+00:00

Slava (slack-strava) connects a Strava account to a chat and posts a card for every activity, complete with map, pace, and elevation, plus commands like connect, disconnect, stats, and leaderboard. In 2023 I ported Slava to Discord by hand, evening by evening over about three weeks, and it took most of that stretch to get a working bot called Strada (discord-strava). This week I ported the same app to Microsoft Teams as Strata (teams-strava) in 3 days instead of the 3 weeks the Discord port took, using time carved out during the Microsoft Global Hackathon. By “I”, I mean GitHub Copilot CLI and I.

The 2023 Baseline

discord-strava’s git history is a fair record of how long a manual port takes. The first commit, “Initial fork from slack-strava,” landed July 30, 2023. “Most interactions working” was three days later. Getting install/help/error-handling polish took through August 20:

2023-07-30 23:56  Initial fork from slack-strava.
2023-08-02 23:46  Most interactions working.
2023-08-03 06:18  Remove PNG retrieval, Discord displays redirects correctly.
2023-08-03 06:26  Removed clubs.
2023-08-03 08:28  Fixed model specs.
2023-08-03 18:20  Fix API specs.
2023-08-04 19:44  Fix command specs.
...
2023-08-08 10:34  Countinously poll with 1 minute intervals.
2023-08-20 22:59  Improved install button and text.

20 commits spread across 9 evenings over roughly three weeks (there’s a real job and a life in between those timestamps). All hand-typed, with GitHub Copilot’s inline autocomplete helping the way it helped everyone in 2023, but no agent driving the actual porting work.

The 2026 Port

teams-strava’s git history is a single continuous Copilot CLI session, 107 conversational turns over three calendar days, and the timestamps compress dramatically:

2026-09-14 11:05  Initial port of discord-strava to Microsoft Teams
2026-09-14 16:39  Fix local dev setup and personal-scope install handling
2026-09-14 16:43  Fix 400 error replying to personal-scope install notice
2026-09-15 08:29  Document CLI-only local dev workflow in DEV.md
2026-09-15 08:41  Fix Graph permission GUIDs and add missing CLI setup steps in DEV.md
2026-09-15 09:03  Fix Strava webhook subscription errors and threaded channel posts
2026-09-15 09:11  Send the Strava connect link via a private 1:1 message
2026-09-15 09:15  Fix broken help rendering in Teams
2026-09-15 09:18  Revert connect to posting in-channel; drop personal-scope DM for now
2026-09-16 08:33  Document production Azure Bot/Entra setup in DEV.md, fix --endpoint flag
2026-09-16 08:46  Add script/verify_production.rb production sanity check
2026-09-16 08:49  Point manifest at production bot, bump version to 1.0.0
2026-09-16 09:10  Make Strata free during beta and fix homepage app download
2026-09-16 09:16  Fix production NameError: rubyzip is a test-only transitive dependency
2026-09-16 09:26  Fix 'Activity resulted into multiple skype activities' error on update

A working bot (connect, disconnect, post activities, help) existed by the end of the first day: five and a half hours elapsed between the first and last commit, but roughly three of those were actually spent hands-on-keyboard, in bursts, with breaks for a normal workday in between.

The next two sessions were where I was genuinely out of my depth: registering an Entra app, wiring up Bot Framework client-credentials auth, building and validating a Teams app manifest, getting the bot into a tenant’s app catalog, and eventually standing up a separate production Azure subscription. I’d never touched any of it before this week. Copilot CLI ran the az and m365 CLI commands, read the error messages back to me, and looked things up (multi-tenant bot registration being deprecated, a missing service principal, a renamed --endpoint flag) faster than I could have found them myself reading Microsoft Learn cold. That’s arguably the bigger win over the 2023 Discord port: not “wrote the Ruby faster” but “got me through an unfamiliar cloud platform’s auth and app-distribution model without me having to become an expert in it first.” Either way, GitHub Copilot CLI got the whole port done in 3 days instead of the 3 weeks the Discord one took, roughly 7x faster.

Copilot CLI’s own usage tracking gives a sense of scale for just that first session: 659 API calls, about 272,000 output tokens generated, and roughly 72.8 million input tokens processed, of which about 71 million were cache reads rather than fresh tokens (the CLI re-sends accumulated context on every turn, and prompt caching is what keeps that affordable). That’s the token cost of a chatty pair-programming session where the “pair” reads the whole codebase back to itself before every reply. The session started on GPT-5.4 for the first 108 calls, then switched to Claude Sonnet 5 for the remaining 551, model choice is a CLI setting, not something baked into the port.

Copilot CLI usage isn’t metered per token, it’s included in a Copilot subscription, so there’s no invoice to point at. But pricing it out at today’s public list prices for comparable models (roughly $3/$15 per million input/output tokens, with cache reads discounted to a fraction of that, cache writes at a slight premium) puts that first session at somewhere around $25-30 of raw model spend, almost all of it cache reads.

This Isn’t a Fair Fight

There’s zero reason to still do this kind of work by hand in 2026. Discord’s bot API is comparatively simple: a webhook, embeds, slash commands. Microsoft Teams brought its own pile of accidental complexity that the AI had to work through, not around: Bot Framework client-credentials auth against Entra ID, Adaptive Cards instead of embeds, a manifest/app-catalog model for distribution, and Teams Store submission requirements that don’t exist for Discord at all. The scope of this port is arguably larger than the 2023 one, and it still took a fraction of the time.

AI of course still makes mistakes:

# TeamsStrava::CardRenderer used to render one Adaptive Card per embed
# (activity + one per photo). Teams' update API rejects an activity
# update with more than one attachment:
#
#   400 BadSyntax: "Activity resulted into multiple skype activities"
#
# Fixed by combining every embed into a single card/attachment.
body = embeds.flat_map { |embed| card_body(embed) }
activity.add_card(::Teams::Cards::AdaptiveCard.new(*body)) unless body.empty?

# rubyzip was only ever required as a transitive, test-only dependency
# of selenium-webdriver, so `zip -j` worked in every spec run and then
# raised NameError: uninitialized constant ...::Zip the first time a
# real user hit the download endpoint in production.
gem 'rubyzip', require: 'zip'

Both bugs shipped, passed a full green test suite, and only surfaced against the real Teams API and the real production environment. That’s not an argument against AI-driven development, it’s an argument for test coverage: when you’re merging on green because you trust the AI wrote the code, and largely didn’t review every line yourself, your test suite is the only thing standing between a passing build and a broken production. A 574-example spec suite at 87.95% line coverage and a clean rubocop run caught plenty, but no test suite covers what it doesn’t know to test, and there’s still no substitute for a production smoke test before you tell people the thing works.

Try It Out

Strata is in beta and not yet listed in the Teams Store, but it’s real and running in production. Head to strata.playplay.io to download the app manifest and sideload it into your own tenant. This is temporary while I go through Teams Store submission; once that’s done, installing will be a one-click affair.

Standardizing Exception Message Style in Ruby

2026-09-05T00:00:00+00:00

While reviewing dozens of PRs from ericproulx optimizing Grape’s internals recently, I noticed that the bare raise ArgumentError, "..." calls scattered across the codebase were inconsistent: some messages were capitalized, some ended in a period, most were not. Longtime readers know where this is going.

Ruby’s own core and standard library exceptions don’t do this - TypeError: no implicit conversion from nil to integer, ArgumentError: wrong number of arguments, and so on all read lowercase and unpunctuated, because the message is meant to be read after the exception class name and a colon, not as a standalone sentence.

Grape’s own Grape::Exceptions::* classes already follow this convention. The bare raise ArgumentError, "..." calls in dsl/entity.rb, dsl/inside_route.rb, dsl/validations.rb, and validations/types/dry_type_coercer.rb didn’t, so I fixed those seven sites and documented the convention in CONTRIBUTING.md, in #2909.

To avoid regressions, I wrote rubocop-exception_messages, a RuboCop plugin gem with two cops:

ExceptionMessages/Casing flags (and autocorrects) messages that don’t start with a lowercase letter.
ExceptionMessages/Punctuation flags (and autocorrects) messages with a trailing period, with an exception for a literal ellipsis ("still processing.."), which is stylistic rather than a sentence ending.

Both cops recognize raise Class, "message" and raise Class.new("message") forms, and handle interpolated (dstr) messages by only checking the literal string segments (the first segment for casing, the last for punctuation), since interpolated values in the middle are out of the cop’s control.

# bad
raise ArgumentError, 'Missing required option.'

# good
raise ArgumentError, 'missing required option'

The gem ships as a modern RuboCop plugin (via lint_roller), so it’s a one-line addition to a consuming project’s .rubocop.yml:

plugins:
  - rubocop-exception_messages

rubocop-exception_messages 0.2.0 is out now, and I’ve added it back to Grape’s own Gemfile and .rubocop.yml in #2909, so the convention it started from is now enforced by CI going forward. Not everyone will agree with my choice of lowercase and unpunctuated, of course, so EnforcedStyle support to configure the opposite convention is available, along with ExceptionMessages/RedundantExceptionName, which flags messages that redundantly repeat the exception class name, and ExceptionMessages/QuoteStyle, enabled by default, which checks that interpolated values in exception messages are consistently marked, e.g. "unknown type: `#{type}`" — the same PR fixed the 16 messages across Grape’s codebase that weren’t.

Standardizing Exception Message Style in Ruby was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 05, 2026.

Adventures in Daylight Saving, Norfolk Island, and Time Zone Math (in Ruby)

2026-08-28T00:00:00+00:00

distance_of_time_in_words is a small Ruby gem that turns two Time objects into a human-readable string like “3 days and 4 hours”. Several separate bug reports against it turned out to be variations on the same theme: computing a duration between two timestamps is not the trivial subtraction it looks like, the moment time zones are involved. The first two fixes shipped in dotiw 5.6.0; four more followed shortly after in dotiw 5.6.1.

Bug 1: `dst?` Lies When You Least Expect It

#63 reported that a duration of one minute was rendered as “less than 1 second” for users in Europe/Dublin. The gem’s TimeHash had a DST correction that looked reasonable:

d = largest - smallest
d -= 1.hour if smallest.dst? && !largest.dst?
d += 1.hour if !smallest.dst? && largest.dst?

The idea: if a DST transition happened between the two times, Time subtraction already accounts for the wall-clock jump, so cancel it back out before splitting the duration into calendar units. That works everywhere except Ireland. Europe/Dublin uses an inverted DST scheme: its winter time is legally defined as “standard time minus one hour” rather than the more common “standard time is winter, summer is +1”. Depending on whether a Time was constructed via Time.at(seconds) or datetime.to_time, dst? could report different values for the exact same instant, even though utc_offset agreed. The correction fired when it shouldn’t have, and a real one-minute gap got silently zeroed out.

Reproducing it doesn’t even require mocking dst? — just running the example with the right TZ set is enough:

ENV['TZ'] = 'Europe/Dublin'

start = Time.at(DateTime.now)
finish = DateTime.now + 1.minute

# => "less than 1 second"
# expected: "1 minute"
distance_of_time_in_words(start, finish)

The fix (PR #152) was to stop asking “is this DST?” and just compare the actual offsets:

def offset_decreased?(smallest, largest)
  smallest.utc_offset > largest.utc_offset
end

def offset_increased?(smallest, largest)
  smallest.utc_offset < largest.utc_offset
end

utc_offset doesn’t care how the Time was constructed or what a particular country calls its winter clock — it’s just the number of seconds off UTC. Reliable, and it doesn’t require knowing anything about Europe/Dublin’s specific legal quirk.

Bug 2: DST Isn’t the Only Thing That Changes an Offset

Fixing #63 with utc_offset comparisons was more correct, but still baked in an assumption: that any offset change is a ±1 hour DST transition. #153 broke that assumption. Running the test suite under TZ=Pacific/Norfolk produced a spurious “23 hours and 30 minutes” leaking into results that should have just been a clean calendar distance.

It turns out Norfolk Island permanently changed its UTC offset from +11:30 to +11:00 on 4 October 2015, announced by the island’s Administrator a month earlier — a one-time tzdata rule change, not a recurring seasonal transition. The old code’s ±1 hour hardcoding had no way to represent a 30-minute, permanent shift.

Again, a real (non-mocked) reproduction is enough — no dst? mismatch involved this time, just a genuine historical offset change baked into tzdata itself:

ENV['TZ'] = 'Pacific/Norfolk'

start = '2015-1-15'.to_time
finish = '2016-3-15'.to_time

# => "1 year, 2 months, 23 hours, and 30 minutes"
# expected: "1 year and 2 months"
distance_of_time_in_words(start, finish, true)

The real fix (PR #154) was to stop special-casing “1 hour” and generalize to whatever the actual offset delta is:

def offset_delta(smallest, largest)
  largest.utc_offset - smallest.utc_offset
end

Here’s why that’s needed, worked out with real numbers. start.utc_offset is +11:30 (41400 seconds) and finish.utc_offset is +11:00 (39600 seconds). Ruby’s Time subtraction (finish - start) already factors that in: it returns 36,721,800 seconds, which is 425 days and 1800 seconds (30 minutes) — not a clean 425 days. That’s correct: 30 real minutes did elapse due to the offset change, so the raw distance is right.

The bug was in the next step, where that distance gets split into years/months/weeks/days. That calendar breakdown doesn’t work from seconds at all — it reads largest.year, largest.month, largest.day and subtracts smallest’s, which are plain calendar fields with no concept of UTC offset. Jan 15 to Mar 15 is a clean “1 year, 2 months, 0 days” by the calendar, no remainder. Meanwhile the old buggy code applied its ±1 hour DST correction before computing the distance (since it still thought in terms of “1 hour”, not the real -1800 second delta), which left the wrong remainder behind: 36,721,800 - 3600 = 36,718,200 seconds, i.e. 424 whole days plus an 84,600-second (23.5 hour) remainder — reported as “23 hours and 30 minutes”. Neither the ±1 hour hardcoding nor the 30-minute reality had anywhere to go once years/months/days had already consumed the calendar-shaped part of the duration, so it leaked out as bogus hours and minutes. Using the real offset_delta (-1800, not ±3600) and applying it consistently everywhere the code touches @distance removes that artifact entirely, leaving just “1 year and 2 months”.

This is a strictly more general version of Bug 1’s fix — the “DST transition” case just falls out as offset_delta happening to equal ±3600 seconds. Once we stopped assuming what kind of offset change was possible, both the recurring and the one-off cases worked with the same code path. The lesson: don’t encode a specific real-world cause (DST, 1 hour) into your math when what you actually care about is a more general effect (offset changed, by however much).

Do Other Languages Have This Problem?

Curious whether this is a dotiw-specific mistake or a trap every “humanize a time difference” library falls into, I reproduced both scenarios — the Norfolk Island offset change and the Dublin DST-adjacent case — against similar libraries in JavaScript, Python, Go, Rust, PHP, C#, Java, Elixir, Swift, Objective-C, and Dart: date-fns, dayjs, moment.js, humanize, arrow, go-humanize, chrono-humanize, native DateTime::diff, Carbon, Humanizer, PrettyTime, Timex, humanizer, RelativeDateTimeFormatter/DateComponentsFormatter, and timeago. All the test code is on GitHub if you want to run it yourself.

Every one of them was clean on the Dublin case, and every one but one was clean on Norfolk too. Here’s the Norfolk Island case in JavaScript (date-fns) and Python (humanize):

process.env.TZ = 'Pacific/Norfolk';
const start = new Date(2015, 0, 15);
const finish = new Date(2016, 2, 15);

// => "about 1 year"
formatDistance(start, finish, { includeSeconds: true });

os.environ['TZ'] = 'Pacific/Norfolk'
start = datetime(2015, 1, 15, tzinfo=ZoneInfo('Pacific/Norfolk'))
finish = datetime(2016, 3, 15, tzinfo=ZoneInfo('Pacific/Norfolk'))

# => "1 year, 2 months"
humanize.naturaldelta(finish - start)

And the Dublin case in Rust (chrono-humanize) and PHP (Carbon, the closest analog to dotiw since it also supports a compound breakdown):

let dstart = Dublin.with_ymd_and_hms(2024, 10, 27, 1, 59, 30).earliest().unwrap();
let dfinish = dstart + Duration::minutes(1);

// => "in a minute"
HumanTime::from(dfinish.signed_duration_since(dstart))

$dstart = Carbon::create(2024, 10, 27, 1, 59, 30, 'Europe/Dublin');
$dfinish = $dstart->copy()->addMinute();

// => "1 minute before"
$dstart->diffForHumans($dfinish);

// => "1 year 2 months" (Norfolk case, compound breakdown, still clean)
Carbon::create(2015, 1, 15, 0, 0, 0, 'Pacific/Norfolk')
    ->diff(Carbon::create(2016, 3, 15, 0, 0, 0, 'Pacific/Norfolk'))
    ->forHumans();

C#’s Humanizer doesn’t attempt a calendar year/month breakdown at all, only weeks/days/hours/minutes, so the Norfolk case has no calendar-shaped bucket to leak into:

var norfolk = TimeZoneInfo.FindSystemTimeZoneById("Pacific/Norfolk");
var start = new DateTimeOffset(2015, 1, 15, 0, 0, 0, norfolk.GetUtcOffset(new DateTime(2015, 1, 15)));
var finish = new DateTimeOffset(2016, 3, 15, 0, 0, 0, norfolk.GetUtcOffset(new DateTime(2016, 3, 15)));

// => "60 weeks, 5 days, 30 minutes"
(finish - start).Humanize(precision: 5);

Java’s PrettyTime only ever formats a single instant relative to another (“1 year from now”), so there’s no compound breakdown at all to leak into:

ZonedDateTime start = ZonedDateTime.of(2015, 1, 15, 0, 0, 0, 0, ZoneId.of("Pacific/Norfolk"));
ZonedDateTime finish = ZonedDateTime.of(2016, 3, 15, 0, 0, 0, 0, ZoneId.of("Pacific/Norfolk"));

// => "1 year from now"
new PrettyTime(Date.from(start.toInstant())).format(Date.from(finish.toInstant()));

Elixir’s Timex, however, does reproduce the bug — same shape as dotiw’s original Norfolk failure, just a smaller leftover because it computes the real offset delta instead of hardcoding an hour:

{:ok, start} = DateTime.new(~D[2015-01-15], ~T[00:00:00], "Pacific/Norfolk", Tzdata.TimeZoneDatabase)
{:ok, finish} = DateTime.new(~D[2016-03-15], ~T[00:00:00], "Pacific/Norfolk", Tzdata.TimeZoneDatabase)

# => "1 year, 2 months, 30 minutes"
Timex.Format.Duration.Formatters.Humanized.format(
  Timex.Duration.from_seconds(DateTime.diff(finish, start))
)

That trailing “30 minutes” is exactly the Norfolk offset delta leaking out, the same artifact dotiw used to produce as “23 hours and 30 minutes” before PR #154. It’s a good confirmation that the bug isn’t a Ruby-specific mistake so much as a natural consequence of building a compound years/months/…/minutes breakdown from a raw second count without accounting for the offset change along the way — most libraries just happen to avoid the compound breakdown (or, in Carbon’s case, avoid the bug despite it) rather than being immune to the underlying trap.

I opened bitwalker/timex PR #793 with a fix, following the same strategy as dotiw’s: instead of formatting an opaque Duration (which has already lost all calendar context by the time it reaches the formatter), the fix adds a format/2 that takes both datetimes directly, computes years/months via real calendar arithmetic, and only converts the true leftover to a duration:

Timex.Format.Duration.Formatters.Humanized.format(start, finish)
# => "1 year, 2 months"

While testing this fix, I also found that format/2 crashes if finish comes before start — negative years/months get passed straight into Gettext’s plural translation, which requires a non-negative count. format/1 has always been sign-independent (Duration.from_erl({0, -65, 0}) and Duration.from_erl({0, 65, 0}) both format the same way), so format/2 should be too. Filed as a follow-up, bitwalker/timex PR #794.

Timex itself is largely unmaintained at this point — the last push to main was mid-2025, and it has more than 70 open issues — so while I was at it, I checked whether a maintained alternative avoids this whole class of bug. humanizer is a small, actively developed, English-only library with a relative_time/2,3 function. It’s clean on both the Norfolk and Dublin cases, and it also handles reversed argument order correctly without crashing — it diffs absolute instants and branches on sign rather than doing calendar-aware year/month shifting, which sidesteps the bug class structurally at the cost of using fixed-width buckets (7/30/365 days) for weeks/months/years instead of exact calendar arithmetic. The reproduction is in the same test repo, under elixir/humanizer_test/.

I later extended the reproduction to Swift, Objective-C, and Dart. Swift and Objective-C share the same underlying Foundation implementation: RelativeDateTimeFormatter/NSRelativeDateTimeFormatter (single-largest-unit “time ago” style) and DateComponentsFormatter/NSDateComponentsFormatter (a compound breakdown, directly analogous to dotiw’s output). All clean — Norfolk, Dublin, reversed order, and zero distance. Dart’s timeago package is clean too.

One thing initially looked like a fourth bug during that pass, worth mentioning because I got it wrong at first. Given a reversed (fromDate, toDate) pair, NSDateComponentsFormatter renders:

NSDateComponentsFormatter *f = [[NSDateComponentsFormatter alloc] init];
f.unitsStyle = NSDateComponentsFormatterUnitsStyleFull;
f.allowedUnits = NSCalendarUnitYear | NSCalendarUnitMonth;
f.calendar = cal; // Pacific/Norfolk

[f stringFromDate:start toDate:finish]  // => "1 year, 2 months"
[f stringFromDate:finish toDate:start]  // => "-1 year, 2 months"

That looks inconsistent — surely it should read "-1 year, -2 months" if the underlying delta is negative in both fields? But this is actually standard mixed-radix negative notation, the same convention used for negative durations (-1:30:00 means minus one-and-a-half hours, not “minus one hour plus thirty minutes”) or negative degrees/minutes/seconds coordinates: only the leading unit carries the sign, and the rest are magnitudes of that same negative quantity. NSCalendar confirms this is intentional: the raw components really are year=-1, month=-2 underneath, and the formatter correctly collapses that into a single leading sign for display, exactly as it should. Not a bug — see the test repo under objc/ and swift/ for the full reproduction and reasoning.

The main reason none of the others reproduce the bug is structural: most round to a single largest unit (“about 1 year”, “a minute ago”) instead of building a compound breakdown across years, months, weeks, days, hours, and minutes the way dotiw does. With nowhere calendar-shaped for a stray 30 minutes or 23 hours to end up, there’s no remainder left to misattribute. Carbon is the exception that proves the rule: it does support a compound breakdown similar to dotiw’s output, and still gets it right, because the offset math happens correctly underneath, at the DateInterval level, before any splitting into units occurs.

One other thing stood out while testing the Dublin case in Rust and C#. Both refuse to let you construct a local time that falls in an ambiguous window (the “fall back” hour that occurs twice) without handling it explicitly. Rust’s chrono-tz:

match Dublin.with_ymd_and_hms(2024, 10, 27, 1, 59, 30) {
    chrono::LocalResult::Single(dt) => println!("Single: {}", dt),
    chrono::LocalResult::Ambiguous(a, b) => println!("Ambiguous: {} OR {}", a, b),
    chrono::LocalResult::None => println!("None (doesn't exist, e.g. spring-forward gap)"),
}
# => Ambiguous: 2024-10-27 01:59:30 IST OR 2024-10-27 01:59:30 GMT

And .NET’s TimeZoneInfo, which surfaces the same fact via an explicit query instead of an enum:

var dublin = TimeZoneInfo.FindSystemTimeZoneById("Europe/Dublin");
var local = new DateTime(2024, 10, 27, 1, 59, 30, DateTimeKind.Unspecified);

dublin.IsAmbiguousTime(local); // => true
dublin.GetAmbiguousTimeOffsets(local); // => [00:00:00, 01:00:00]

Ruby (and most of the other languages tested) will silently pick one interpretation of an ambiguous wall-clock time and move on. Forcing the caller to disambiguate explicitly is exactly the kind of design that would have made a bug like #63 harder to write in the first place.

Bug 3: Two Unrelated Offsets Aren’t a Transition

offset_delta from Bug 2 fixed the “real transition” case, but it introduced a subtler mistake: it assumed any two Time values with different utc_offsets must represent the same clock crossing a real transition, and folded the difference in unconditionally. #160 showed that’s not true. Comparing a Time pinned to UTC against a Time pinned to a fixed -08:00 offset — two clocks that have nothing to do with each other, no shared tzdata history, no transition between them — still triggered the same folding logic:

start = Time.utc(2026, 1, 15, 12, 0, 0)
finish = Time.new(2026, 1, 15, 12, 0, 30, '-08:00')

# => "less than 1 second" (8 hours silently subtracted)
# expected: "8 hours"
distance_of_time_in_words(start, finish)

The fix (PR #161) added a same_clock? guard before applying offset_delta at all — only fold the offset when both Times plausibly represent observations of the same underlying clock (same system zone abbreviation, both non-UTC, etc.), not merely because they happen to disagree on offset:

def offset_delta(smallest, largest)
  return 0 unless same_clock?(smallest, largest)

  largest.utc_offset - smallest.utc_offset
end

Bug 4: `to_time` Doesn’t Always Mean the Same Thing

Shipping same_clock? immediately raised the next question: what actually counts as “the same clock”? #162 is a case where two ActiveSupport::TimeWithZone values, in two different named zones (Asia/Tokyo and America/Los_Angeles), get converted to plain Time via #to_time before reaching dotiw. The Time#zone accessor is normally a String (a zone abbreviation like "JST") or nil for a fixed offset — same_clock? treated any two non-nil #zones as good enough. That was true until Rails 8.0, where to_time_preserves_timezone = :zone became the default (permanent as of 8.2): TimeWithZone#to_time now returns a plain Time whose #zone is the actual ActiveSupport::TimeZone object, not a string. Two different zone objects both being “not nil” made same_clock? say yes to two completely unrelated zones, and the real 1-hour difference between Tokyo and Los Angeles got folded away into “less than 1 second” again — but only on Rails >= 8.0. Reproducing it needed the Rails 8 code path specifically:

tokyo_time = ActiveSupport::TimeZone['Asia/Tokyo'].local(2026, 1, 16, 4, 0, 0).to_time
la_time = ActiveSupport::TimeZone['America/Los_Angeles'].local(2026, 1, 15, 12, 0, 0).to_time

# On Rails >= 8.0: tokyo_time.zone and la_time.zone are both TimeZone objects (not strings),
# so the old same_clock? treated them as "the same clock" and folded the 1-hour gap away.
# => "less than 1 second" on Rails >= 8.0, "1 hour" on Rails <= 7.2
distance_of_time_in_words(tokyo_time, la_time)

The fix (PR #163) taught same_clock? to actually compare the zone objects for equality instead of just checking they’re both present:

def same_clock?(smallest, largest)
  if smallest.respond_to?(:time_zone) || largest.respond_to?(:time_zone)
    smallest.respond_to?(:time_zone) && largest.respond_to?(:time_zone) &&
      smallest.time_zone == largest.time_zone
  elsif !smallest.zone.is_a?(String) || !largest.zone.is_a?(String)
    !smallest.zone.nil? && smallest.zone == largest.zone
  else
    !smallest.zone.nil? && !smallest.utc? && !largest.zone.nil? && !largest.utc?
  end
end

This one is a good reminder that a library’s own dependencies can quietly change the shape of the objects you’re handed. dotiw never called to_time itself — a Rails minor version bump changed what Time#zone returns for values constructed elsewhere entirely, and the bug only showed up for people on the new default.

Bringing In More Test Cases

Since both of these bugs turned out to have prior art elsewhere, I went back through the test suites of the libraries surveyed for Bug 2/3 — Luxon’s diff tests, Timex’s humanized-duration tests, and the tz_test reproductions — and pulled in the ones that translate directly into dotiw regression examples: a UTC-vs-CEST offset comparison from Luxon (PR #166) and the historical Norfolk Island offset change (PR #167), both passing cleanly against the fixed same_clock?/offset_delta. (These started life bundled together in a single PR #164, later split apart once it became clear the third example below needed materially different treatment.)

The Timex-derived case — a Europe/Dublin DST fall-back, one real minute elapsing across the clocks-back transition — turned up a fifth wrinkle while adapting it: same_clock? correctly recognizes both timestamps as the same clock (they really are the same TimeZone object), so offset_delta still folds in the full 1-hour offset change. But here the actual elapsed time is only 60 seconds — smaller than the offset delta being folded in — so the correction overshoots and produces a negative corrected distance, again collapsing to “less than 1 second” instead of “1 minute”. Unlike Bugs 3 and 4, this isn’t about misidentifying whether two Times are the same clock; it’s that the folding math assumes the real elapsed time is always large relative to the offset shift, which breaks down right at the boundary of a transition. Filed as #165 and fixed in PR #169: the offset correction now only ever applies to the sub-day leftover, once the distance has already been split into calendar fields, rather than to the top-level distance used to decide which calendar branch (build_years, build_days, etc.) to take in the first place — so a genuinely tiny elapsed time can no longer be pushed past zero by a much larger offset shift.

Bug 5: An Unforced Conversion, Not a Rails Version Limitation

Verifying the #165 fix across every supported Rails version turned up one more thing. The regression spec for #165’s sibling case — the Norfolk historical offset change, this time expressed as ActiveSupport::TimeWithZone values rather than plain Time — only passed on Rails >= 8.0. On Rails < 8.0, it failed with a spurious “1 year, 2 months, and 30 minutes” instead of “1 year and 2 months”, suspiciously similar to the very bug #154 had already fixed. I was pairing with an AI coding assistant on this fix, and its first instinct was to shrug this off as an inherent Rails < 8.0 limitation (the same to_time_preserves_timezone distinction from Bug 4) and skip the spec on older Rails.

That instinct was wrong, and it took me pushing back — “the following code should always give the correct answer, no?” — before it looked closer instead of accepting its own shortcut. The real cause: distance_of_time_in_words unconditionally called #to_time on any TimeWithZone argument before doing anything else with it:

from_time = from_time.to_time if !from_time.is_a?(Time) && from_time.respond_to?(:to_time)

On Rails < 8.0, TimeWithZone#to_time (without to_time_preserves_timezone set) returns a plain Time in the process’s local system zone, discarding the actual zone entirely — which is exactly the information same_clock? needs to recognize two readings as the same clock across a transition. But nothing about TimeHash actually needs a plain Time in the first place: TimeWithZone already supports every operation it performs — subtraction, #advance, #year/#month/#day/#hour, #utc_offset — without ever being converted. The #to_time call wasn’t a Rails-version workaround at all, just an unforced, avoidable conversion that happened to only cause visible damage before Rails 8.0’s default changed what it produced.

Filed as #170 and fixed in PR #167 with a coerce_to_time helper that leaves Time and TimeWithZone arguments untouched, only calling #to_time on genuinely non-Time-like values (Date, DateTime):

def coerce_to_time(value)
  return value if value.is_a?(Time) || value.respond_to?(:time_zone)

  value.respond_to?(:to_time) ? value.to_time : value
end

With that in place, the Norfolk TimeWithZone example (and the #165 Dublin fall-back example) both pass on every supported Rails version, 7.0 through 8.1, with no skip required — a stronger fix than the version-gated one I’d initially assumed was necessary.

The Common Thread

All three failure modes share a shape: a plausible-looking shortcut (dst? instead of utc_offset, “correct by exactly 1 hour”, “convert to a plain Time up front”) that works for the overwhelmingly common case and quietly breaks for a specific, real-world edge case that a bug reporter with an unusual time zone eventually ran into. None were caught by the existing test suite, because the test suite ran in one time zone, on inputs that never crossed the affected boundaries — and, in Bug 5’s case, on only one version of Rails.

The actual fix was the same in spirit each time: replace the specific assumption with the general, verifiable fact it was standing in for — actual offsets instead of a DST flag, an arbitrary delta instead of a fixed hour, and no conversion at all where none was ever needed. If you maintain a library that touches wall-clock time, it’s worth asking, for every “obvious” shortcut in the code, what real-world weirdness it’s quietly assuming doesn’t exist — and, per Bug 5, whether “this only works on newer Rails” is really a platform limitation or just an unforced move your own code is making. Europe/Dublin and Pacific/Norfolk are more common exceptions to your assumptions than you’d think.

Adventures in Daylight Saving, Norfolk Island, and Time Zone Math (in Ruby) was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 28, 2026.

Benchmarks Are Free Now

2026-08-15T00:00:00+00:00

My previous post walked through four bugs in ruby-enum, a gem I maintain, all stemming from the fact that class-level instance variables aren’t inherited by subclasses. The third fix, #59, made keys, key?, value?, key, value, to_h, parse and each walk up superclass and merge in a parent’s enums, so a subclass would see everything its ancestors defined. It was correct, fully tested, and shipped. It also made every one of those methods roughly 5x slower on any subclass.

def _enum_hash
  if superclass < Ruby::Enum
    superclass.send(:_enum_hash).merge(_own_enum_hash)
  else
    _own_enum_hash
  end
end

This recomputes the merged hash, walking the entire ancestor chain, on every single call. There’s no caching. A one-level subclass calling .value pays for building a brand new hash, on top of the superclass doing the same, every time. The test suite didn’t notice because tests check correctness, not speed, and correctness was fine.

I only found this because I asked Copilot CLI to add a benchmark script comparing lookups at different inheritance depths, mostly out of curiosity about how the “Benchmarks” section of the README would read next to the new feature. It took one prompt and about a minute to get a working script:

class Colors
  include Ruby::Enum
  define :RED, 'red'
  define :GREEN, 'green'
end

class SubColors < Colors
  define :BLUE, 'blue'
end

class SubSubColors < SubColors
  define :YELLOW, 'yellow'
end

benchmark('base class (no inheritance)', n) { Colors.value(:RED) }
benchmark('subclass (1 level)', n) { SubColors.value(:RED) }
benchmark('sub-subclass (2 levels)', n) { SubSubColors.value(:RED) }

The first run told the story immediately: a 1-level subclass’s .value calls took roughly 5x as long as the base class, and a 2-level subclass was worse still. Nobody had written this benchmark before merging #59 because writing a throwaway benchmark script used to feel like more ceremony than it was worth for a one-off performance check. Now it’s a single sentence to an agent, and the script stays in the repo afterward as a rake benchmark:inheritance task anyone can rerun.

The fix was small: memoize the merged hash and invalidate the cache only when define adds a new entry.

def _enum_hash
  @_enum_hash ||= if superclass < Ruby::Enum
                    superclass.send(:_enum_hash).merge(_own_enum_hash)
                  else
                    _own_enum_hash
                  end
end

Re-running the same benchmark after the fix (#60):

--- .value lookups, by depth of inheritance ---
base class (no inheritance): 0.0627
subclass (1 level): 0.0608
sub-subclass (2 levels): 0.0606

Subclass lookups are now indistinguishable from the base class, regardless of depth. I also had Copilot CLI write a second benchmark (#61) comparing basic Ruby::Enum operations against plain Ruby equivalents, since I was about to write a README claim about the gem’s overhead and didn’t want to write “negligible” without a number to back it up. Constant access turned out to be free (Colors::RED is exactly as fast as a plain Ruby constant), but hash-backed lookups like .value and .key? carry a real, if small, 3-5x cost versus calling Hash#[] directly - the price of the extra method dispatch and object wrapping Ruby::Enum does. Worth knowing, not worth avoiding the gem over. That number, along with the exhaustive Ruby::Enum::Case matcher’s much larger 50-100x overhead versus a native case statement, is now spelled out in a dedicated Performance section in the README, so nobody has to ask or guess.

None of this changes the underlying lesson that a performance regression is easy to introduce and easy to miss when your tests only check correctness. What’s changed is the cost of catching it. Writing a benchmark script used to be the kind of thing you’d skip on a Friday afternoon for a “just a getter method” change. Now, benchmarks are free.

Benchmarks Are Free Now was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 15, 2026.

Ruby Instance Variables Are Not Inherited (and Why That Breaks Your DSL)

2026-08-14T00:00:00+00:00

The ruby-enum gem is a small library I maintain that adds enum-like behavior to a class via include Ruby::Enum and define :KEY, value. Four pull requests landed against it recently, each fixing a different symptom, and all four turned out to be the same underlying bug: class-level instance variables set in a module’s included hook are not inherited by subclasses the way you might expect. All of these fixes shipped in ruby-enum 1.2.0.

Ruby::Enum stores its keys and values in instance variables on the class itself, set up when the module is included.

def self.included(base)
  base.extend ClassMethods
  base.instance_variable_set(:@_enum_hash, {})
  base.instance_variable_set(:@_enums_by_value, {})
end

This works fine for a single class. It gets interesting the moment subclasses or class reloading show up.

A user opened #56, reporting DuplicateKeyError from a Rails console after a class that had already defined its enums got reloaded. It reproduces without Rails.

class_body = proc do
  include Ruby::Enum

  define :RED, 'red'
end

Colors = Class.new(&class_body)
Colors.class_eval(&class_body) # raises DuplicateKeyError

Rails’ development-mode autoloader re-evaluates a class body, and the second define :RED sees @_enum_hash still holding RED from the first load, so the duplicate-key check fires. The fix clears the hash whenever Ruby::Enum is included, rather than assuming it’s always a fresh class. The contributor that reported the problem and submitted the fix also caught a sneakier variant: a subclass that redundantly re-includes Ruby::Enum (include is supposed to be idempotent, right?) was wiping out enums inherited from its parent, because included unconditionally reset the instance variables:

class OtherSecondSubclass < FirstSubclass
  include Ruby::Enum # redundant, but shouldn't lose FirstSubclass's enums

  define :MAGENTA, 'magenta'
end

Thanks, Nazar, for tracking both of these down with tests.

Months later, #49 surfaced a related crash: a subclass that never calls define itself, just inheriting from a parent that does, blew up on .values.

class Colors
  include Ruby::Enum

  define :RED, 'red'
end

class SubclassWithNoOwnDefines < Colors
end

SubclassWithNoOwnDefines.values # NoMethodError: undefined method `values' for nil

This is because @_enum_hash is only ever set in two places: the included hook, and redundantly again in define. A subclass that inherits Ruby::Enum transitively and never calls define runs neither, so its own @_enum_hash is nil. This is the crux of it: SubclassWithNoOwnDefines.instance_variable_get(:@_enum_hash) and Colors.instance_variable_get(:@_enum_hash) are two completely separate variables, even though one class is a subclass of the other. Instance variables, unlike methods, don’t look up the ancestor chain.

Eight methods (keys, key?, value?, key, value, to_h, parse, each) had this bug, just with less obvious failure modes. The fix in #58 was to stop reading the raw @ivar directly and go through a private reader that lazily defaults to an empty hash.

def _enum_hash
  @_enum_hash ||= {}
end

Once a subclass with no enums of its own correctly returned an empty list instead of crashing, the obvious next question was whether it should instead see its parent’s enums, the same way it sees inherited methods. Thus, #59 extended all eight methods to walk up superclass and merge in inherited enums, with a subclass’s own definitions taking precedence when they overlap.

def _enum_hash
  if superclass < Ruby::Enum
    superclass.send(:_enum_hash).merge(_own_enum_hash)
  else
    _own_enum_hash
  end
end

Same lesson, opposite direction: since @_enum_hash isn’t automatically inherited, subclass-aware behavior has to be built by hand, walking superclass and merging state explicitly.

Recomputing that merge on every single call is correct but wasteful - O(depth) work per lookup with no caching. I benchmarked it (more on that in a follow-up post) and found a one-level subclass paid a 5x tax on .value lookups versus the base class. #60 memoized the merged hash, invalidating it only when define adds a new entry.

Class-instance-variables in Ruby - @ivar set on a class object, as opposed to instance-level @ivars on regular objects - are per-class. They aren’t inherited, and reloading a class doesn’t reset them for you. If a gem’s DSL needs subclass-aware or reload-safe behavior, that has to be built in explicitly: clear state on include, default lazily instead of assuming initialization already ran, and walk superclass yourself if you want inheritance-like semantics.

Ruby Instance Variables Are Not Inherited (and Why That Breaks Your DSL) was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 14, 2026.

Generating AI Descriptions of Automated Pull Requests

2026-08-11T00:00:00+00:00

The slack-ruby-client library, an open source Ruby gem I maintain, runs a scheduled GitHub Actions workflow that regenerates code from Slack’s API definitions and opens a pull request with the diff. The commit message and CHANGELOG entry used to be a generic “Update API (2026-08-11)”, which told a reviewer nothing about what actually changed. Here’s how we taught the workflow to describe its own diffs, using GitHub Copilot CLI, which open source maintainers can get for free.

The Idea

The workflow already computes a diff before opening the pull request. Instead of a boilerplate commit message, we pipe that diff through an LLM and ask it to summarize what changed, then use the response as the commit message and PR body.

- name: Check for changes
  id: changes
  run: |
    if git diff --quiet; then
      echo "changed=false" >> "$GITHUB_OUTPUT"
    else
      echo "changed=true" >> "$GITHUB_OUTPUT"
    fi
- name: Prepare diff for AI summary
  if: steps.changes.outputs.changed == 'true'
  run: |
    git diff --stat | sed 's/^/      /' > /tmp/diff_stat.txt
    git diff | head -c 20000 | sed 's/^/      /' > /tmp/diff.txt

The sed 's/^/ /' indent isn’t decorative. actions/ai-inference substitutes template variables as raw text into a prompt YAML file before parsing it, so a multi-line diff starting at column 0 breaks the indentation of the enclosing content: |- block scalar. Pre-indenting the file to match keeps the YAML valid no matter what the diff looks like.

The Prompt File

actions/ai-inference supports .prompt.yml files, a small convention for keeping the system/user prompt out of the workflow YAML.

messages:
  - role: system
    content: |-
      You write CHANGELOG entries describing an automated API update to slack-ruby-client, a
      Ruby gem whose Web API endpoint methods, argument validations, specs, and bin commands
      are code-generated from vendored Slack API method definitions (via a git submodule and
      rake task).

      Given a diffstat and a diff of the regenerated files, respond with ONLY a single JSON
      object (no markdown code fences, no other text) in exactly this shape:
      {"entries": [string, ...]}

      Rules for entries:
      - Each entry is a single short line, imperative mood, no leading bullet/dash and no
        trailing period (the caller adds both).
      - Group related changes together into one entry per notable change or affected method
        group, rather than one entry per file.
      - Focus on developer-visible API surface changes: new/removed/renamed methods, new/
        removed arguments, validation changes.
  - role: user
    content: |-
      
      

Asking for a single line per group of changes, rather than per file, matters, a single Slack API update can touch dozens of generated files for one conceptual change (adding an argument to five related methods, say), and nobody wants five identical CHANGELOG lines about it.

Wiring It into the Workflow

- name: Generate changelog entries with AI
  if: steps.changes.outputs.changed == 'true'
  id: ai
  uses: actions/ai-inference@v1
  with:
    prompt-file: ./.github/prompts/changelog-entries.prompt.yml
    file_input: |
      diff_stat: /tmp/diff_stat.txt
      diff: /tmp/diff.txt
- name: Build changelog entries
  id: entries
  run: |
    entries=""
    if [ "$" = "true" ]; then
      response_file="$"
      echo "AI changelog response:"
      cat "$response_file" || true
      json_line="$(grep -E '^\{.*\}$' "$response_file" 2>/dev/null | tail -n 1)"
      if [ -z "$json_line" ]; then
        echo "::error::AI changelog response did not contain a JSON object, see response above."
        exit 1
      fi
      entries="$(printf '%s' "$json_line" | jq -r '.entries[]? // empty')"
    fi
    if [ -z "$entries" ]; then
      entries="Update API ($)"
    fi

A few defensive touches worth calling out. The step always logs the raw AI response, so a bad run leaves a paper trail in the logs. Rather than trying to parse the whole response file as JSON, it greps for the last line that looks like a JSON object (^\{.*\}$) and parses just that: Copilot CLI sometimes narrates its reasoning (“Let me check the diff…”, “Now I have enough info…”) before printing its final answer, and naively parsing the entire file as JSON would either crash on that narration or, worse, silently discard a perfectly good response. Finally, if no such JSON line is found at all, the workflow fails loudly with ::error:: instead of quietly falling back to a generic changelog entry, an earlier version of this step swallowed genuine parsing failures and it took a couple of confusing scheduled runs to notice.

Once we have the entries, we use them both as the commit message/PR body and to insert one CHANGELOG line per group, all referencing the same (predictable, since GitHub allocates them sequentially) PR number:

lines = entries.map do |entry|
  "* [##{pr_number}](#{pr_url}): #{entry} - [@slack-ruby-ci-bot](https://github.com/apps/slack-ruby-ci-bot)."
end.join("\n")

You Can’t Use GitHub Models

If you’re setting this up today, skip GitHub Models as the backend, it was retired on July 30, 2026 and actions/ai-inference no longer talks to it at any version. The v1 tag, in particular, doesn’t float to the rewrite, it’s stuck resolving to the old GitHub-Models-only code, so don’t expect a version bump to fix things automatically. The current major version, v3, speaks exclusively to GitHub Copilot CLI instead, which changes a few things about the setup:

- name: Set up Node
  uses: actions/setup-node@v6
- name: Install Copilot CLI
  run: npm install -g @github/copilot
- name: Generate changelog entries with AI
  if: steps.changes.outputs.changed == 'true'
  id: ai
  uses: actions/ai-inference@v3
  with:
    prompt-file: ./.github/prompts/changelog-entries.prompt.yml
    model: ''
    file_input: |
      diff_stat: /tmp/diff_stat.txt
      diff: /tmp/diff.txt
  env:
    COPILOT_GITHUB_TOKEN: $

Copilot CLI has to be installed on the runner (the action doesn’t bundle it any more), authentication is via COPILOT_GITHUB_TOKEN rather than the old token input, and responseFormat/jsonSchema inputs are gone entirely, hence asking for bare JSON in the prompt and parsing it defensively, as above. We also set model: '' explicitly; the action’s built-in default (gpt-4.1) isn’t necessarily available on every Copilot plan, and an empty string tells the CLI to fall back to whatever model it has access to.

For the token, if your org has a paid Copilot Business or Enterprise plan, you can enable “Allow use of Copilot CLI billed to the organization” and grant the workflow the copilot-requests: write permission, then the built-in GITHUB_TOKEN just works, no secret needed. Free organizations (like slack-ruby) don’t have that option, since free Copilot access for open source maintainers is granted to individual maintainer accounts, not organizations, so the fallback is a personal fine-grained PAT with the “Copilot Requests” account permission, stored as a COPILOT_PAT secret.

Testing Before Merging

Both workflows have a github.repository == 'slack-ruby/...' guard so they don’t run on forks by accident, which also means we can’t just dispatch them there to test. We got around this by pushing a disposable branch to our own fork, temporarily overriding the guard (if: true), adding a throwaway step to force a non-empty diff (the real scraping step usually finds nothing new on a given day), and dispatching manually.

gh workflow enable "Update API" --repo dblock/slack-ruby-client
gh workflow run "Update API" --repo dblock/slack-ruby-client --ref test-copilot-cli
gh run watch <run-id> --repo dblock/slack-ruby-client --exit-status

This is how I caught both the missing-token and the unavailable-model issues above, neither of which was obvious from reading the action’s README.

Links

Generating AI Descriptions of Automated Pull Requests was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 11, 2026.

Coding with AI Agents is Now a Baseline Expectation for Managers

2026-05-05T00:00:00+00:00

AI-first Engineering is now the operating default in many organizations, including mine. Developers have kept up. Vibe coding became agentic engineering, and the race towards truly autonomous engineering isn’t slowing.

But what are we, managers, to do?

A manager job continues to include recruiting and retaining people, setting clear goals and expectations, fostering communication, owning team workflows, and coaching daily behaviors. To this list we must now add driving AI transformation.

Being a passive advocate is not enough. Unlike other subjects, no amount of AI training will help you keep up with the pace of evolution of this technology. Therefore, one cannot drive AI transformation without being an active AI practitioner. But what does being an active AI practitioner look like for a manager?

To find out, I landed myself into a small Engineering team (7 people) within my 100+ people organization five weeks ago. This small group develops an essential internal Microsoft system used by every single Engineer at the company. I wanted to learn firsthand about their challenges by onboarding into the project, and maybe contribute 2-3 PRs myself. I decided to dedicate my Copious Free Time™ to this work, to only use Copilot (you can use Claude, or another CLI, too), and to attend the team’s daily standup.

Before I talk about what I did or learned, I must apologize to the team for giving them a heart attack upon my arrival. It’s rare that a VP of Engineering, many levels “above”, inserts themselves into any team unless there’s some huge, urgent, problem. This wasn’t an issue with the specific team, but transforming the way we work remains absolutely urgent, and it’s my responsibility to do everything I can to make it happen.

Initially, I expected to make 2-3 pull requests. Instead, I was able to make 89 (!), broke at least two production features, but also shipped some meaningful improvements. These fell into several categories.

Improved developer experience. I fixed several issues in local dev, wrote a new CONTRIBUTING guide, added a script to start and shutdown various services together, and added an AGENTS.md to make the repo AI-agent-ready.
Did batch dependency upgrades to address CVEs. Major upgrades required rework of the actual code. Two of these silently broke features in very subtle ways, showing gaps in integration testing, but also taking a lot of team’s time to debug unexpectedly.
Increased test coverage and overall repo quality. I wrote a number of missing unit and integration tests and fixed a few flaky ones. A clear win.
Improved CI/CD pipeline. I was able to bring the CI time down from over an hour to ~30 minutes, mostly by not building projects without code changes, and disabling the many checks and guards that didn’t need to run on every pull request.
Executed some overdue modernization. I finished a Webpack to Vite migration that another engineer stalled on because of conflicting priorities, significantly improving local build time, upgraded TypeScript 4 to 5, Node.js 16 to 20, LESS to SCSS, MSTest 2.x to 3.x. All these upgrades were on the team’s backlog, but nobody ever had time to do them.
Fixed many minor bugs. Other than bugs reported by users, I paid attention to warnings during build or in the JavaScript console, and asked Copilot to address them. I improved error display, corrected dark mode CSS, addressed sass deprecation warnings and ESLint errors.

Here’s what I learned.

This AI sh*t is wild. Driving Copilot is like holding the reins of a Russian winged troika. The only limitation was my own time, memory, and the amount of changes I was able to keep active in my head in parallel at one given time. I’d come up with a thing to do, tell Copilot to do it, it would make the change, open a pull request, get it reviewed by another AI, address comments, and iterate to green. I would intervene once this loop was finished, review the change, and mark it as ready to be reviewed by another Engineer.
We are absolutely not ready for the onslaught of agent-generated changes. Human attention quickly became the bottleneck. If a manager with a full-time job can open 20+ pull requests per week that pass CI and accomplish a positive change, a group of 5 full-time engineers plus an army of autonomous agents will be generating hundreds. The team immediately wondered whether they would go from being developers to full-time code reviewers, while real breaking changes slipped through otherwise trivial updates.
Copilot is the new rubber duck, developer social, and software architect. It’s now much faster to ask Copilot to explain a problem and then to fix an issue than to discuss any of it with teammates. It’s faster to design and implement 3 versions of a feature than to discuss which approach is cleaner ahead of time. You can now truly lead with code.

But the most interesting thing that happened during this experiment is that the team’s PR velocity doubled without counting mine. Using Copilot became contagious. I am confident this is permanent — I never want to write code by hand again. There’s no turning back.

If you manage a team of any size and have never coded with AI at work, become the janitor of one of your team’s repos. Start by improving onboarding docs and CI/CD time. Doing this work was both impactful and a lot of fun. Feel the energy!

Coding with AI Agents is Now a Baseline Expectation for Managers was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on May 05, 2026.

How I Made $360 by Serving Markdown to A.I. agents from My Jekyll Blog

2026-04-11T00:00:00+00:00

In April 2025 I wrote Apologizing for My Obsessiveness Over Punctuation, a post about my various organizational compulsions. Near the end, almost as an aside, I mentioned that I obsessively categorize expenses in Monarch, a personal finance app, linking it with my referral code. That post earned me exactly one referral in the nine months that followed.

Then, on January 15th, 2026, I wrote Serving Markdown for AI Agents. The idea is simple: for every post on this blog, there’s now a .md version at the same URL. AI agents can discover and fetch clean markdown instead of parsing HTML. I didn’t think much of it.

Exactly thirty days later - the length of Monarch’s free trial — I started getting a stream of referral conversion notifications without any change in SEO traffic.

Eighteen signups.

Twelve converted to paid. At $30/referral, that’s $360.

We live in the future.

How I Made $360 by Serving Markdown to A.I. agents from My Jekyll Blog was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on April 11, 2026.

Opening Proprietary Code to Contributors Checklist

2026-04-08T00:00:00+00:00

Before AI coding assistants, a typical engineering team built expertise with the years: new team members joined, contributed small bug fixes, then were given more ambitious tasks over time as they became more comfortable in a codebase, to ultimately become experts. This process took years.

In contrast, today, almost every engineer, and many non-engineers, have access to tools that can gather context from any codebase, and produce a large volume of high-quality code in a day. This lowers the bar for contributing meaningful changes to the software we build and enables many more individuals without domain or codebase expertise with good ideas to see them to light.

At work, I asked my team to actively seek contributions from our customers with an active engagement for our proprietary code. Inspired by the open-source model, we are reviewing our systems from the angle of a newcomer easily contributing to them.

Here’s a checklist to apply to any repo.

Create a single landing CONTRIBUTING.md that welcomes contributors and encourages them to contribute while insisting on higher standards, such as needing to write automated tests with every contribution.
Make your source code repo discoverable. Your source code README, and your product or tool should have a visible link to your single CONTRIBUTING.md.
Include a simple to follow “Getting Started” checklist in CONTRIBUTING.md that enables any developer at the company to make a trivial change in the application and submit a pull request.
Ensure that your project has an automated test suite that runs in CI, is trivial to run locally, has few to no dependencies, and has enough coverage to give confidence to any new contributor that they did not break key functionality.
Evolve every project to a state where a minimum viable version of it can run locally without the need to ask for permissions, certificates, or keys, install or get access to unnecessary dependencies, removing those barriers from the new contributor path. Describe how to run the project locally in CONTRIBUTING.md.
Ensure safe CD by making the project’s deployment model self‑describing, clearly signaling where changes land first, what approvals and gates exist, and how regressions are detected and rolled back, so both new and existing contributors can ship changes with confidence.
Prefer GitHub fork/PR model where contributors do not need permissions to your source code and protect source such that contributors cannot accidentally force push an update to main.
One should be able to open a PR without ever needing to contact your team that owns the project.
Enable and encourage contributors to open bugs and feature requests directly and triage new issues weekly. Engage customers publicly within these systems rather than offline or e-mail.
Establish a publicly accessible channel for your own developers and for contributors to meet and ask technical questions and link it from CONTRIBUTING.md.
Create a daily short standup for your team that is open to others actively contributing to your repo to drop into and make it easily discoverable. Use the standup to socialize external contributions across the team.
Create a habit of all team members reviewing and approving PRs and delegate repetitive requests, such as needing tests, to A.I. reviewers. Ensure that both team PRs and PRs made by external contributors are engaged within one day, and that all team members are reviewing and approving each other’s PRs regularly, not just one person.
Create an automated CHANGELOG or a Release Notes process that highlights both team and external contributors, and that is discoverable from your product or tool. Take the time to directly highlight one’s contribution to their manager when impactful.
Make the repo AI-friendly with AGENTS.md that contains instructions for AI that help humans collaborate with AI to produce a feature.
Continue prioritizing most impactful features to be shipped by your own team while actively engaging your customers by inviting them to contribute the features that you cannot deliver quickly. Highlight external contributions in business reviews.

And if nobody volunteers to contribute to our projects, most of these steps will also make it easier and more efficient for my own team members to work on the codebase, to enable partner teams to do work, and reduce the time needed to onboard new engineers joining my organization.

Level up!

Opening Proprietary Code to Contributors Checklist was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on April 08, 2026.

AI Slop: A Slack API Rate Limiting Disaster

2026-03-12T00:00:00+00:00

Yesterday I described AI-generated code as “plausible-looking, locally coherent, globally wrong.” Here’s a concrete example from my own codebase.

I needed a cleanup job to close old Slack group DM conversations in my slack-sup2 app. The AI-generated solution looked perfectly reasonable:

def close_old_sups!
  return 0 unless sup_close
  
  old_sups = sups.where(conditions)
  old_sups.each(&:close!)
  old_sups.count
end

def close!
  return unless conversation_id
  return if closed_at
  
  logger.info "Closing DM channel #{conversation_id}..."
  slack_client.conversations_close(channel: conversation_id)
  update_attributes!(closed_at: Time.now.utc)
end

This code looks pretty great and completely breaks the app. Slack’s API has a global rate limit of 1 request per second for the conversations.close endpoint. So, when this job runs against a workspace with hundreds of old conversations, it immediately hits the rate limit. Worse, because rate limits are global across all endpoints, it takes down the entire application. Every other API call — posting messages, fetching user info, everything — starts failing.

I asked AI to address this. It made the fix catastrophically worse.

def close!
  # ... existing code ...
  begin
    slack_client.conversations_close(channel: conversation_id)
  rescue Slack::Web::Api::Errors::TooManyRequests => e
    sleep_time = e.retry_after || 60
    sleep(sleep_time)
    retry
  end
  # ... rest of method ...
end

In socketry/async, sleep() blocks the entire fiber and prevents other concurrent operations from executing. You should use Async::Task.sleep() instead, but that still doesn’t solve the fundamental architectural problem of making hundreds of sequential API calls.

What made this particularly insidious is that the assistant wrote some pretty professional-looking code and seemingly handled obvious edge cases. Yet, it failed to consider the distributed system constraints or global invariants. The rate limiting problem wasn’t visible in the local scope of the method - it was a system-wide concern that required human judgment.

So, how did I actually fix the problem? I used the initial A.I. implementation (4c11b3a0), but moved the task into the 30 minute cron to avoid triggering global rate limits (ab9e9518). I then put the feature behind a setting that is off by default and wrote a script to slow-drain the many thousands of unclosed DM channels for existing customers (9feabd2c). Finally, I … ahem … Copilot refactored the code to auto-close a limited number of DMs at any given time to avoid the rate limit altogether (#94).

For now, human oversight of A.I. assistants remains critical.

AI Slop: A Slack API Rate Limiting Disaster was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on March 12, 2026.

Right-Sizing Engineering Teams for AI

2026-03-11T00:00:00+00:00

Before AI coding assistants, a typical engineering team of 8-10 people might have been lucky to have one or two “10x engineers”, or “workhorses”, the kind of engineer that both keeps project quality and feature velocity high.

AI tools have solved the workhorse half of this equation, enabling massive raw output. Today, almost every engineer can produce a high volume of code with GitHub Copilot, Claude, or Cursor.

But the quality half of the equation has not kept up. Teams are shipping more code, but a greater fraction of it is AI slop: plausible-looking, locally coherent, globally wrong. Code review remains a human activity. Until that changes, AI assistants cannot substitute for the senior engineer. If AI triples output but the number of senior reviewers stays the same, the ratio of experienced judgment to code produced has gotten roughly 3x worse.

The instinctive response to higher individual productivity is to hire fewer people, which is correct directionally but wrong in practice if you cut experience rather than volume. The difference is not in lines of code produced; it is in the accumulated judgment applied at every decision point. A team of four or five senior engineers with AI assistants will, in my experience, outperform a team of ten mixed-experience engineers with the same tools because the ratio of judgment to output stays healthy.

This has implications for how engineering leaders should think about headcount planning. A well-functioning engineering team today should be five to seven people, with at most one junior. A reliable signal that you’ve gotten this wrong: pull requests that sit unreviewed for days, not because people are busy, but because no one feels confident enough to approve them.

Smaller, more experienced engineering teams are not a new idea - Fred Brooks noted that you cannot make a late project earlier by adding people. What AI has done is make the argument sharper and more urgent. When every engineer can produce the volume that once required three, the scarcest resource is no longer effort; it is experience. Optimize for that.

Right-Sizing Engineering Teams for AI was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on March 11, 2026.

The Golden Ratio of Manager to IC

2026-02-04T00:00:00+00:00

In today’s shocker, Meta is to “create a new applied AI engineering organization aiming for an ultra-flat structure of up to 50 employees to one manager”.

Like all software engineers I, too, tend to apply a data‑driven, mathematical approach to every problem in the world. Yet I would have chosen a more romantic number and applied the golden ratio: roughly 1.6:1, the proportion that shows up in seashells, galaxies, and every second slide about “natural elegance”, rather than 50:1, a measure that feels less like harmony and more like a spreadsheet’s idea of efficiency.

The idea of flattening an organization is not new and can be a good one. I know plenty of managers who have not done any individual contributor work, code or otherwise, in years. This is particularly striking with former strong coders who are promoted to managerial roles. After 2–3 cycles of promotions they are so far detached from what’s happening at the individual‑contributor level that they become 100% overhead, spending their entire life in meetings and actively preventing real work from being done. It’s natural to want to eliminate layers of such people as they simply don’t have any impact. And so, the real news at Meta is that it’s fighting its own organization design in which, at least in some teams according to my friends who work or have worked there, people managers are discouraged from doing deep technical work, don’t own much beyond process, and mostly serve as reporting‑structure placeholders.

Another reason to flatten an organization is the introduction of AI assistants that have created a major shift in the capabilities of individual contributors. Two years ago you could maybe find one single “10x engineer” in every team—someone who has dramatically higher velocity than their peers. A good manager would recognize these extraordinary abilities, make such an individual their right hand and technical partner, share the responsibility of advancing a project, create effective mentorship, and help bring the rest of the team along, distributing work in ways that optimize for the long term where juniors are grown slowly and incrementally. But with AI every engineer can—and in fact must—become a 10x engineer, fast. It therefore makes sense for a flagship AI team to hire already experienced, top‑1% engineers and not bother with juniors, thus requiring fewer managers.

The role of the manager must continue to evolve, but it has fundamentally not changed in my opinion. It remains critically important for any level of manager to be a role model and to deliver results. In a healthy team a manager has time to do some individual‑contributor work, and that is my favorite kind of manager. Today, this could mean using AI assistants to write some code. Beyond that, a manager’s job is to take ownership, articulate a vision and mission, disambiguate and provide clarity to their team, work with customers, recognize and show people what they are capable of, enable human aspirations, and take responsibility for shortcomings. If a manager does “real work”, it matters less how many people report to them; we want a team sized to the problem we are trying to solve, to create the right kind of focus, rather than to enforce a ratio.

An organization is just a tool to delineate responsibilities and provide clarity of purpose to groups of people. When we begin adjusting ratios, we forget that we are working with humans, and that like all metrics, the number is not the goal.

The Golden Ratio of Manager to IC was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on February 04, 2026.

Serving Markdown for AI Agents in Jekyll

2026-01-15T00:00:00+00:00

Dries Buytaert recently wrote about The Third Audience. For decades, websites have targeted two audiences: humans and search engines. AI agents are now the third audience, and most websites aren’t optimized for them yet.

AI agents prefer clean, structured content over HTML. Markdown is ideal - it’s readable, semantic, and free of navigation chrome. So I made this blog serve its source markdown files alongside the HTML.

How It Works

For every post like /2026/01/15/serving-markdown-for-ai-agents.html, you can now fetch the source at /2026/01/15/serving-markdown-for-ai-agents.md.

AI agents can discover this via a <link> tag in the HTML head:

<link href="serving-markdown-for-ai-agents.md"
      type="text/markdown"
      rel="alternate"
      title="Markdown">

Implementation

Since this is a GitHub Pages blog, custom Jekyll plugins don’t work. Instead, I added a GitHub Actions workflow that builds Jekyll and copies the markdown source files to _site before deployment.

The workflow extracts the date and slug from each post filename and copies it to the matching URL path with a .md extension.

Should You Do This?

Dries raises a valid concern: are we just making it easier for AI companies to use our content without sending traffic back? Perhaps. But AI agents are already crawling our sites. Giving them cleaner input might lead to better attribution and more accurate responses that reference our work.

The web has always been about making information accessible. This is just the next evolution.

Plus, we will soon all work for AI anyway, so might as well get on its good side.

Turning Hypermedia APIs into MCPs

2025-09-18T09:00:00+00:00

I’ve written and talked extensively about Hypermedia APIs for about a decade. The HATEOAS constraints in representing resources for a RESTful API has numerous advantages in API design, readability, discoverability, and performance over a hand-rolled REST API. Unfortunately, adoption of Hypermedia APIs is very low compared to, for example GraphQL, but I find the implementation a lot simpler and continue adding Hypermedia APIs to my pet projects.

At its root a Hypermedia API looks like so.

{
  "_links": {
    "self": {
      "href": "https://sup2.playplay.io/api"
    },
    "status": {
      "href": "https://sup2.playplay.io/api/status"
    },
    "team": {
      "href": "https://sup2.playplay.io/api/teams/{id}",
      "templated": true
    },
    ...
  }
}

The above example is an extract from this API. For this post we will use one of my Slack bots called S’Up, which generates fresh triads of team members in Slack to meet for coffee every week in an informal standup. The bot is open-source and you can try it here.

Because the Hypermedia API structure is fixed with only “resources” and “links” (and similar to API frameworks such as GraphQL) you don’t need an application-specific client to interact with the API. In Ruby, the most popular generic Hypermedia client is Hyperclient.

With the API above, a client can retrieve the bot status, and using an API token obtained from an existing installation some team information.

api = Hyperclient.new('https://sup2.playplay.io/api') do |client|
  client.headers['X-Access-Token'] = ENV.fetch('TOKEN', nil)
end

status = api.status
puts "Bot is #{status.ping['presence']['presence']}."

team = api.team(id: '1234')
puts "Team name is '#{team.name}'."

This will output “Bot is online.” and “Team name is ‘dblock’.” for my installation.

In this case, the generic client knew nothing about “team” - it was discovered programmatically and was, in a way, self-documenting. Unsurprisingly, this idea of templated resources is reused almost exactly the same way in the model context protocol (MCP). Therefore, we can easily turn any Hypermedia API into an MCP server generically with a new gem called hyperclient-mcp.

gem install hyperclient-mcp
1 gem installed

Start by using the command-line hyperclient-mcp to discover resources.

$ hyperclient-mcp --api=https://sup2.playplay.io/api resources

Hyperclient::Mcp::Resources::Root
Hyperclient::Mcp::Resources::Status
Hyperclient::Mcp::Resources::Subscriptions
Hyperclient::Mcp::Resources::CreditCards
Hyperclient::Mcp::Resources::Teams
Hyperclient::Mcp::Resources::Channels
Hyperclient::Mcp::Resources::Users
Hyperclient::Mcp::Resources::Rounds
Hyperclient::Mcp::Resources::Sups
Hyperclient::Mcp::Resources::Stats
Hyperclient::Mcp::Resources::User
Hyperclient::Mcp::Resources::Channel
Hyperclient::Mcp::Resources::Team
Hyperclient::Mcp::Resources::Round
Hyperclient::Mcp::Resources::Sup
Hyperclient::Mcp::Resources::Data2

Then run the MCP server.

hyperclient-mcp --api=https://sup2.playplay.io/api --header X-Access-Token=$TOKEN start

Listening on http://0.0.0.0:9292

Add the MCP to Claude.

claude mcp add --transport sse local http://127.0.0.1:9292/mcp/sse

Ensure it works.

$ claude mcp list
Checking MCP server health...

local: http://127.0.0.1:9292/mcp/sse (SSE) - ✓ Connected

Try claude with “use the local mcp and find out the bot status” or “use the local mcp to find the name of the team with ID 1234”.

While this was interesting, Claude actually supports Hypermedia APIs natively. It might need help with passing the access token, which can be forced by telling to “just use curl”. YMMV.

╭───────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code!                         │
│                                                   │
│   /help for help, /status for your current setup  │
│                                                   │
│   cwd: /Users/dblock/source/hyperclient-mcp       │
╰───────────────────────────────────────────────────╯

> given a hypermedia api in https://sup2.playplay.io/api what are available resources

⏺ I'll help you discover the available resources in the hypermedia API at https://sup2.playplay.io/api.

⏺ Fetch(https://sup2.playplay.io/api)
  ⎿  Received 1.4KB (200 OK)

⏺ The hypermedia API at https://sup2.playplay.io/api provides the following resources:

  Collection Resources:
  - Status - API status endpoint
  - Subscriptions - Subscription management
  - Credit Cards - Payment method management
  - Teams - Team collections with filtering
  - Channels - Channel collections with filtering
  - Users - User collections with filtering
  - Rounds - Round collections with filtering
  - Sups - Sup collections with filtering
  - Stats - Statistics with filtering

  Individual Resources:
  - User - Individual user by ID
  - Channel - Individual channel by ID
  - Team - Individual team by ID
  - Round - Individual round by ID
  - Sup - Individual sup by ID
  - Data - Individual data by ID

  Most collection endpoints support query parameters like cursor, size, sort, offset, total_count, and
  filtering by team_id, channel_id, round_id, and active status.

> find out the bot status

⏺ Fetch(https://sup2.playplay.io/api/status)
  ⎿  Received 378 bytes (200 OK)

⏺ The bot status shows:

  Authentication: ✅ Connected
  - Team: dblock
  - User: sup2

  Presence: 🔴 Away
  - Online: No
  - Connection count: 0
  - Manual away: No
  - Auto away: No

  The bot is authenticated but currently offline/away with no active connections.

> find the name of the team with ID 1234

⏺ Bash(curl -H "X-Access-Token: ...."
      https://sup2.playplay.io/api/teams/...)
  ⎿ {"id":"...","team_id":"T04KB5WQH","name":"dblock","active":true,                   
    "subscribed":true,"created_at":"2023-03-15T22:46:33.517Z","updated_at":"2025-09-10T14:17:18.698Z","_l
    inks":{"channels":{"href":"https://sup2.playplay.io/api/channels?team_id=..."},"
    … +6 lines (ctrl+o to expand)

⏺ dblock

Hyperclient-mcp is on GitHub.

Turning Hypermedia APIs into MCPs was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 18, 2025.

Using AI to Reduce the Burden of Status Reporting

2025-08-29T09:00:00+00:00

One of the negative side effects of having any top-down command structure is that every additional layer risks introducing a new level of bureaucracy, which then actively subtracts value. Consider the Politburo of the USSR with dozens of offices of skilled bureaucrats. Because most produced no actual value, the best apparatchiks spent their entire time managing up to remain in control. Individuals who tried to upend the system either became exhausted and gave up, or were deported to Siberia.

The Soviet example also applies to software development. Consider a typical CEO → CTO → VP of Engineering → Director → Manager → Technical Lead → IC command structure. Each project team consists of a technical lead and a handful of individual contributors. The people committed to the project do not need status reports to know what’s going on, they are actively working on it. The stakeholders and the hierarchy, however, naturally want progress and status reports. This gets aggregated at Director level, then at VP level, the CTO, and finally the CEO.

From the point of view of every manager in this hierarchy collecting status and asking questions feels very natural. After all, it’s much more efficient to get a summary of what’s going on from a line manager than to read every status update or code change yourself. You have the power to call a meeting, have things explained and summarized to you. You also have the authority to make snap judgments based on this carefully crafted summary and partial information, and the responsibility to tell the team to focus on something they likely already know. This system quickly promotes those who are good at reporting the things their manager wants to hear, and encourages political behavior as people learn to navigate the system rather than focus on outcomes.

It’s worth acknowledging that these hierarchical structures exist for good reasons. Large organizations need coordination, resource allocation, and strategic alignment. The problem isn’t hierarchy itself, but rather when hierarchies become focused on control rather than enablement, when they add process without adding value, and when they create distance between decision-makers and the work being done.

So, as senior managers, we have a responsibility to prevent excessive status reporting from happening, and the solution in 2025 is remarkably simple! Use A.I.

Today’s A.I. can replace 95% of status reporting toil and remove the need for most status meetings. Your project management system should be reading all work channels (GitHub, Slack, etc.) and automatically summarizing progress weekly in a draft that gets published with minimal edit by each project’s team lead. Build this summarization all the way up to the CEO, make all updates visible to everyone at the company, and eliminate meetings with an audience of one. Shopify has such a system, called GSD (Get Shit Done), and it works remarkably well. It also feels similar to the open-source CHANGELOG, which I have learned to appreciate over the years.

But now, whether you’re an IC or a CEO, you actually have to read those summaries! This is how you learn the real progress being made on projects, and gain the credibility to ask meaningful questions in public project or team channels. Personally, I make sure to spend time reading relevant project summaries and catching up to current state before engaging in any meaningful discussion with anyone.

So what is a pointy-haired boss to do if not status meetings? As a manager, your primary responsibility is building and aligning teams. Spend the vast majority of your time hiring and retaining people, identifying leaders who produce good outcomes, and giving them more resources. Communicate and over-communicate strategy, mission and vision. Use the time saved from status reporting to be deeply involved in one or another project by doing deep work.

The best managers understand that their job is to make themselves less necessary, not more important. They build systems and teams that can operate effectively without constant oversight, and they focus their energy on removing obstacles rather than creating them. Stop asking your team for status, create a system where you can find out for yourself.

Using AI to Reduce the Burden of Status Reporting was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 29, 2025.

How to Disagree and Commit like Switzerland

2025-08-03T09:00:00+00:00

The most abused principle in dysfunctional organizations is “Disagree and Commit”. In Don’t Tell Engineers What to Do I said that “telling people what to do, especially if they are in your direct reporting chain, must not be mistaken for “Disagree and Commit”.

So, what is a healthy “Disagree and Commit”?

The best example I know is the Swiss government. Even when individual members of the Federal Council personally oppose a popular initiative, they publicly defend and implement it once it’s approved, acting as a unified body. This approach ensures stable governance and respect for democratic decisions, as officials set aside personal views to uphold the collective will and present a united front.

I was born in the USSR where people had opinions, then the Party decided. Then, I became Swiss in my teens, and lived in Geneva for 9 years. Having had this experience, it became quite obvious to me that the Swiss system was more sustainable, and I have always been impressed with it.

In this post I will teach you how to be Switzerland.

The keys to a healthy disagree and commit are to 1) identify the individual competent to make a decision, 2) lay out the arguments for one decision vs. the other, 3) let the decision maker decide, 4) collectively commit to the outcome sought by the decision.

Identify the individual competent to make a decision

A decision requires clarity about who has the authority and expertise to make the final decision. It’s best to identify this person upfront, not after disagreements arise, usually through a strong sense of ownership in the organization.

When identifying the decision maker remember that a local decision is faster and cheaper than a decision at a higher level, and you never want a team that is so helpless that to reach to the manager for every small decision.

Begin by separating “one way door” and “two way door” decisions. The former cannot, or may be very costly to “walk back” (e.g. adding a public API), while the latter can easily be undone (e.g. choosing a JSON parsing library). Critical, one way door decisions, will need more scrutiny, but two way door decisions can be made lower in the hierarchy. In both cases, look for the decision maker that is the true owner of the work in question. Who will be affected by this decision daily? Who is taking risks? Assuming we will have made the best decision, who will be celebrated as being right when the project is done? That should be the owner of the decision.

When making a significant one way door decision, look for a trusted tie breaker with authority in the hierarchy of the organization. At Amazon, Principal Engineers often step in as tie-breakers for any technical decision. For non-technical decisions use the organizational hierarchy to find the common denominator (e.g. a common manager). Be careful escalating the ask, though - the more senior the manager, the least context they have, and therefore are susceptible to the most articulate arguments (form vs. substance). In dysfunctional organization you will also find a lot of pass-through “leaders” who will refuse to make a decision and escalate to their manager, delaying the decision significantly. Watch a Director ask for more data, then question the existence of the whole project.

In general, I am of the opinion that a technical decision should almost never be made by a manager. A people manager carries organizational weight, often has veto power (can tell people what to do), usually has the least amount of detail regarding any technical decision no matter how technical they are, and will not be suffering the consequences of the decision on a daily basis.

Lay out the arguments for one decision vs. the other

Once the decision maker is identified, all parties must present their arguments clearly and respectfully. Good arguments include data, examples, risks, and benefits, and should be written down. The goal is to ensure the decision maker has all relevant information and perspectives before making their choice and to get on the same page (literally). This prevents decisions made in ignorance, and ensures that even unpopular choices are made with full awareness of the alternatives. Soliciting broad input at this stage creates more visibility and therefore is an opportunity to FYI the decision to your manager or a senior staff member. Don’t be scared, ask other people’s opinions now! Give everyone time to think about the problem and to sleep on it.

It’s critical that everyone can agree that each option is complete and viable, including yourself. Instead of thinking how you dislike one option (the cons), think in terms of its advantages and disadvantages (both pros and cons) and learn to articulate the pros, too. Finally, if you are the decision maker, avoid writing “recommended” next to any of the options until the last moment not to bias the group.

Let the decision maker decide

After all arguments are presented, the decision maker must be given the space and authority to make their choice without interference. This means no lobbying after the fact, no attempts to undermine the decision, and no passive-aggressive resistance.

Don’t lie by saying “I’d prefer the team to decide”, when, in fact, you’d prefer to decide, and don’t flex your decision making power, it just shows how insecure you are at wielding it. If you are a manager asked to make a decision in a room with subordinates, try saying “These are well laid arguments. I will let the team decide.” as much as possible, then side with the majority. And if you are the most senior member of the technical staff, never say “I am the Principal Engineer, therefore I decide” - everyone already knows it, and that just makes you look like a d*ck.

The decision maker should explain their reasoning, and document the decision. Once the choice is made, it becomes the team’s direction. This requires trust in the decision maker’s judgment and a commitment to respect their authority, even when the outcome differs from one’s personal preference.

Collectively commit to the outcome sought by the decision

Everyone, regardless of their initial position, must fully commit to implementing the chosen direction. This means actively working toward the success of the decision, not just grudgingly complying. You must be able to explain and advocate for the decision to others, as if it were your own choice. This collective commitment transforms a potentially divisive decision into a unified team effort, ensuring the organization moves forward together rather than being pulled apart by lingering disagreements.

If you disagreed with the option chosen, this is your time to earn trust and commit visibly. I’ve recently disagreed with a decision made by a Principal Engineer to remove an emergency status from a project that gave the team extraordinary authority to pull additional resources in. This was an easy “disagree and commit” for me. The reasons were clearly laid out and while I had my pros and cons for the option to keep the emergency status, those were no longer relevant after the decision was made. After the PE made the decision I wrote: “This is an easy disagree and commit for me, because I do agree that the project had achieved its original goals, and understand that the emergency status may no longer needed because problems should be resolved business as usual”. Since then, I have defended the decision like it was mine.

How to Disagree and Commit like Switzerland was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 03, 2025.

code.dblock.org | tech blog

Porting My 1996 Pascal/Delphi Calculator to Rust (CLI + MCP)

The 1996 Original

The 2026 Port

Some Interesting Math

Try It Out

Links

Using AI Effectively in Technical Writing

Serving Markdown for AI Agents, Now as a Jekyll Plugin

What Changed

What About llms.txt?

Meta

In Meetings, Raise Hands Before Reading

Porting a Discord Bot to Microsoft Teams, Entirely With AI

The 2023 Baseline

The 2026 Port

This Isn’t a Fair Fight

Try It Out

Links

Standardizing Exception Message Style in Ruby

Adventures in Daylight Saving, Norfolk Island, and Time Zone Math (in Ruby)

Bug 1: dst? Lies When You Least Expect It

Bug 2: DST Isn’t the Only Thing That Changes an Offset

Do Other Languages Have This Problem?

Bug 3: Two Unrelated Offsets Aren’t a Transition

Bug 4: to_time Doesn’t Always Mean the Same Thing

Bringing In More Test Cases

Bug 5: An Unforced Conversion, Not a Rails Version Limitation

The Common Thread

Benchmarks Are Free Now

Ruby Instance Variables Are Not Inherited (and Why That Breaks Your DSL)

Generating AI Descriptions of Automated Pull Requests

The Idea

The Prompt File

Wiring It into the Workflow

You Can’t Use GitHub Models

Testing Before Merging

Links

Coding with AI Agents is Now a Baseline Expectation for Managers

How I Made $360 by Serving Markdown to A.I. agents from My Jekyll Blog

Opening Proprietary Code to Contributors Checklist

AI Slop: A Slack API Rate Limiting Disaster

Right-Sizing Engineering Teams for AI

The Golden Ratio of Manager to IC

Serving Markdown for AI Agents in Jekyll

How It Works

Implementation

Should You Do This?

Meta

Turning Hypermedia APIs into MCPs

Using AI to Reduce the Burden of Status Reporting

How to Disagree and Commit like Switzerland

Identify the individual competent to make a decision

Lay out the arguments for one decision vs. the other

Let the decision maker decide

Collectively commit to the outcome sought by the decision

Bug 1: `dst?` Lies When You Least Expect It

Bug 4: `to_time` Doesn’t Always Mean the Same Thing