We do "agile" but the one thing that saved this project was writing an actual document

Fifteen years as a BA, mostly financial services, now in-house on a payments team. We're agile in the way most enterprises are agile, which is standups and Jira and a lot of confidence that stories will explain themselves.

Last year we migrated a settlement engine. Big, boring, high-blast-radius work. The kind where a wrong assumption doesn't show up in a demo, it shows up two weeks later as money in the wrong account.

I got pushback for wanting to write a proper interface spec. "That's waterfall, we don't do big docs, put it in the stories." So I split it. The day-to-day stayed in tickets. But the contract between our engine and the bank's, every field, every edge case, what happens on a partial settlement, went in one document that we all agreed to before anyone wrote code.

That document caught three fights before they happened. The bank thought a reversal reused the original reference. We thought it got a new one. If that had lived in a Jira comment thread, it would've been a production incident. Because it lived in a signed spec, it was a twenty-minute call.

I'm not anti-agile. Stories are fine for the parts of a system that are cheap to get wrong and cheap to fix. But there's a category of work where the cost of a misunderstanding is enormous, and for that, sitting down and writing the thing out is still the best tool we have. Agile didn't kill the spec. It just made people embarrassed to write one.

Curious where the rest of you draw that line. What's worth a real document on your projects and what genuinely belongs in a story?