ai-factory decisions: why the code looks like this