Narrate each step of auto-detection cascades
Designing CLI tools that auto-detect environment/config and branch behavior based on what they find.
When a script does auto-detection that branches behavior (e.g. "is the app in docker or on the host?"), narrating each check on stderr converts opaque magic into auditable decisions. The pattern: print what you're checking, print what you found, print which branch you took, and ALWAYS print how to override. Without narration, when detection guesses wrong the user has no idea where the cascade landed or what knob to turn — the tool just silently does the wrong thing. The narration cost is ~3 log lines per check; the debugging cost without it is users opening issues asking 'why does it think X?' Use stderr so the narration doesn't pollute stdout if the script is piped.
When writing auto-detect logic that picks between modes, narrate every check on stderr as a habit, and always mention the override flag in the narration of the final decision.