If you have been around long enough, you may remember the "standard" disk repair utility which shipped with Kickstart/Workbench versions 1.x and 2.0, which was dropped when Workbench 2.1 was introduced.
Whenever a floppy disk error came up, as they did in those early days, you would see an AmigaDOS requester window urging you to repair your floppy disk with the "Disk doctor" command. Many of us tried, because there was practically no alternative, and very few succeeded. Because it had such a poor track record, it became a running joke. You had to be really desperate to use "Disk doctor", because like it or not, "Disk doctor" mostly left the disk in a poorer state than it was before, but sometimes it succeeded in "rescuing" data.
So, why exactly did it work so poorly? I did some research this week, because I was curious.
The purpose of "Disk doctor" was to return a damaged volume back to operational state again after the disk validator or the Amiga ROM file system had failed to achieve this. Specifically, "Disk doctor" was supposed to make the disk validator work again, by repairing the on-disk data structures, even reconstructing the first block and the root directory from scratch if necessary.
To this end, it scanned the entire disk, figuring out which disk block contents were still sound, and if there were any read errors. This was the first step at which things could go very wrong. If "Disk doctor" found that the first block of the disk, or the root block, were unreadable, it would first attempt to rewrite their contents and then reformat these blocks as a last resort (this could correct "hard errors"). However, it would not just format these individual single blocks, it would format the entire track instead of just that block. So you lost not just the contents of one block, you lost 11 blocks of data. Because "Disk doctor" overwrote those blocks with the contents of whatever was last in its scan buffer, random data was repeated all over those 10 trashed blocks.
And it only got worse from there. By knocking out those blocks, "Disk doctor" could damage file contents, would later detect that corruption and subsequently delete those files. Deletion was incomplete in that the data structures which allow for directory scanning would be damaged, and "Disk doctor" was unaware of the need to repair them. This in turn rendered the disk validator inoperable.
Mind you, pre-existing damage to file contents had the same knock-on effect: "Disk doctor" detected the file damage, but did not know that it had to repair the directory data structures. Once a directory was corrupted, "Disk doctor" would never repair it.
"Disk doctor" version 1.3.3 (and presumably older versions, too) suffered from a bug in the initial scanning process. It failed to scan the entire portion of the disk which was used by the file system, omitting the final two blocks. If there was a file or directory header stored there, or a file data block, then "Disk doctor" would assume that these directory entries did not exist, or that the files associated with the "missing" data blocks were corrupt.
As part of its recovery operation "Disk doctor" identified files and directories whose parent directories no longer had valid parent directories themselves. These were considered "orphaned" directory entries, because they were no longer reachable through the existing directory structures. "Disk validator" would add these orphans to the root directory, making them accessible again. This may sound reasonable, but there was a twist: if several orphaned files shared the same name, they would all show up in the root directory. If you tried, as the "Disk doctor" documentation recommended, to copy the contents of the "corrected" disk to a separate disk, only one of those orphans which shared the same name would be copied. Trying to delete those files with the same name on the corrected disk would most likely lead to all of them getting deleted.
That was, of course, not the end of it. "Disk doctor" had trouble recovering files which were longer than 72 blocks of data (on a floppy disk, that would be 36865 bytes or larger). Due to how the Amiga ROM file system works, a file covering more than 72 blocks of data (assuming a block size of 512 bytes) needs to record where the other blocks are stored in a separate data structure called the "extension block list".
"Disk doctor" ran into trouble with the extension blocks because of a mix-up in the disk read routines. One version read blocks, verified that their contents were sound and that the block was of a certain type. The other version did not insist on checking all of that, and it did not have to. The problem was that "Disk doctor" used the version which insisted that the block had to be of a certain type, which happened not to match the extension block type. Hence, "Disk doctor" considered all files larger than 72 blocks to be corrupt and would schedule them for deletion. Which had further knock-on effects, corrupting the directory structures.
This still is not the end of the tale. "Disk doctor" used an incredible amount of memory for its internal bookkeeping. You might have been able to "correct" a floppy disk with its 1760 blocks on your 512 KByte Amiga (which would require 140 KBytes of RAM), but with a 20 MByte hard disk partition you would need at least 1 MByte of RAM. In the early days, that was a lot to ask for.
"Disk doctor" reached the end of its usefulness (for some values of "useful") when it turned out to be too hard to adapt it for use with the Fast Filesystem (FFS) in 1988. Commodore struggled to find a proper fix for its limitations, but the basic problem was that so much of "Disk doctor"'s code was restricted to the original Amiga ROM file system layout and operations.
How directories and data blocks look like is notably different for the FFS, but confusion prevailed. The documentation for the last "Disk doctor" version 1.3.5 manages to both discourage and encourage you at the same time to use it with FFS volumes. As it turned out, if you were so unlucky to try, "Disk doctor" could render perfectly workable FFS format directory structures unsuitable for use with the FFS. If you were spectacularly unlucky (the first disk block was unreadable), "Disk doctor" would simply assume that your volume was actually in standard Amiga ROM file system layout and then make it so: when rewriting the first disk block, it always assumes that the disk uses the original Amiga ROM file system layout.