How to figure shit out when no one tells you

Creature Labs released a commented version of the Creatures 3 COS files. Fortunately for you, these COS files represent the majority of the game you'll be messing with. Find them and read them.

Docking Station's COS files come annotated by default. Read those too.

Keep in mind CL was in major crunch time and compared to later tricks people figured out their CAOS is relatively bad. So if it looks like a bug, it probably is.

In Jagent, or with Revelation, you can 'decompile' other peoples' agents. Look at their code. Some people may be upset that you do this; they don't need to know. Just don't copy their code word-for-word, it won't work in your agent anyway. (And there's only so many ways to do certain things in the game...?! And the code is not exactly run 'encrypted', and knowing what it's doing is highly relevant to your playing of the game)

If you don't feel like decompiling an agent but need to check something it's doing, check out the caos commands SORC, GIDS and FILE OOPE. Mind that GIDS is one of those weird two-word CAOS commands so GIDS on its own won't work, you prolly want GIDS SPCS most of the time

You might find it beneficial to keep a small library of agents you've decompiled, in fact. (I don't, but I'm also mostly doing fairly uncommon tasks with the language) You'll definitely find it beneficial to keep the annotated C3 and DS bootstraps somewhere outside of a game directory to look at.

Find out to 'search in files' on your computer. For me it's grep -r "string" . (this is part of why I don't do my development on the same Windows PC that runs DS) For you it's likely to be something very different. Figure it out, and make it easy to get to; you'll be looking for usage examples of  CAOS commands a lot.

(I also keep a copy of the stock 'images' and 'sounds' folders, since the engine will lock files that are in use and not allow any other process to access them, and I sometimes have to look at them to see what some stock COS is doing to them, esp for more confusing sprites like GUI sprites; You'll also need them to make sure your agent's dependencies are actually part of the base game, if you're using base game assets.)

Learn a little rudimentary C, then C++ to be able to make sense of the more horrifying error messages the engine throws at you. (C2E is written in C++ largely.) You may be able to find out why your world suddenly corrupted, for example. (You may not necessarily be able to do anything about it; but if it's a quick 'remove a file' fix, awesome.) Also, a lot of mysterious tables (IMSK's key numbers, ATTR's bitmask) are no longer mysterious when you have this basic knowledge.

Read the CAOS documentation. It's extremely exhaustive and you're lucky to have it. Sit down and read it for fun. Take it very literally. Pay attention to unclear or unspecified parts and go try the CAOS in your game and find out the missing parts. Don't just use the alphabetical version, or vice versa; export the categorical version and go through it as well, you'll run into commands you skimmed over the first time.

Seriously, Keep the CAOS docs open and a hand ready to jump to ctrl-f at all times.

Make a notebook. I think paper is best, because transcribing command descriptions and encounters by hand helps me to remember them, but you do what you want. (Paper also allows you to draw code flow diagrams, which is much more difficult in text, and vital in CAOS because the variables you're tracking are often unnamed)

Especially, keep a reference of all your quick 'debugging' CAOS macros (count agents of a type, output a variable from all agents of an ID, etc.) You will need them, as you won't remember them after you set the code down a couple of days.

Learn about unit tests, and think about 'what would I do to prove that this code reliably works' when writing your scripts and subroutines.