The dialog box practically writes itself. "Sorry! Your iPhone has just recovered from an oopsie-poopsie caused by a tired battery. Please choose an option: <Continue operating normally for as long as possible> <Reduce performance to extend battery life> <Schedule an appointment at your nearest Genius Bar to install a new battery (and check out the new iPhones!)>"
It's utterly inexplicable the way they handled this. Someone should have been fired. But then we say that a lot about Apple around here, and it never seems to happen.
Depending on what limit has been hit, it's quite likely there is no way to log the cause of the error. Low voltage protection circuitry on most batteries doesn't have a status line. It's never supposed to trigger except in exceptional cases, and it just cuts power. All you know is that the power disappeared suddenly, and you've rebooted. Telling the difference between that and assorted other hardware faults, especially if you never designed the hardware to look for it, is really difficult.
You can certainly design a system that will latch the cause of the shutdown in the battery management IC - but you can't really add this in after the fact.
As lithium batteries age, their internal resistance goes up - you can model a battery as a voltage source and a series resistor accurately enough. Over time, that resistance goes up, which means, for a given current, you end up with less voltage "at the output." Most power supplies will compensate by pulling more current to provide the needed power, which will drop the voltage more until you slam into the low voltage protection circuitry that cuts power.
The Nexus 5s are the ones I'm most familiar with, and they absolutely had this problem with one of the battery OEMs (the only way to tell which OEM you had was to pull the battery out, they were labeled on the back). The typical symptom was, "The phone shuts down when you try to take a picture," because camera modules are power hungry, the CPU was spinning hard to keep up with rendering the view from the camera (and possibly doing some pre/post frame capture to find the best frame, I don't recall when that showed up), and the flash pulls a LOT of current, very briefly. So everything would simply shut down when you hit the button to take the picture.
Apple decided to attempt to limit this problem, and they locked out the highest tiers of CPU performance (which are the most power hungry), if the device was having brownout issues. It's a reasonable enough strategy. Where they failed (IMO) was in not alerting the users that it was happening, or that it was a battery health issue. The later iterations of it, where it tracks battery health, and will tell you if your battery is going bad and needs replacement, are what they should have rolled out, and didn't. My guess is that they didn't think it was going to be a major issue for many devices, so it was just a CYA sort of thing that would prevent shutdowns. Unfortunately, that also happened right around the same time that US carriers started dropping the "New phone every 2 years on contract!" thing, and so the iPhones of that era started being used rather substantially longer than the previously-expected 2 years, and, Apple, so drama for clicks.
Had they just gone about telling users, "Hey, it looks like your battery is getting weak, would you like to schedule a replacement? Otherwise, we've limited performance slightly to prevent shutdowns." - I think it would have been fine. And they did settle on that eventually. It just took a few iterations.