I needed to set up some drush commands (which is always awesome) for kicking off a batch process of some uploaded directories. The process was working on the file system, and the task needed to check a root directory, find xml files, crunch those files into nodes and then mark the file as being processed. Not a complex task -- I got this.
First gotcha: I'm working from my profile directory. So, how does that change things? Well, after spending 2 hours to determine that -- yes, you have created your drush command correctly - but since you are working from a module that resides under <docroot>/profiles, your newly created command does not display when just running drush. I wasn't alone in having this problem, and it has since been addressed by the Drupal community at d.o issue: http://drupal.org/node/827888
Second gotcha: my other issue with my new drush commands had to do with understanding what assumptions drush makes about its running environment. With my command I was changing directories to locate xml files to process and pull images packaged with-in the directory. The bug that kept popping up was after a certain point was that drush would try to run its commands and then would just die. This gave odd "run-level" errors and even function not found errors. Perplexed, I went through line by line of my code and discovered that drush was expecting to be in a certain directory when running. So through all my directory changing, I was my own problem.
I was able to fix all this by wrapping my code with:
$cwd = getcwd();
<do a bunch of stuff here>
At the time I was cursing drush. Then after figuring out my issue, it made perfect sense why drush was doing what it was doing. In short, your code is always doing what YOU told it to do. It doesn't hate you, want to do you harm, or even shave off your beard (http://on.fb.me/save-erics-beard). In most cases, you are just overlooking something obvious. Just not obvious at the time. ;)