Check the environment.
Python version, path access, free disk, optional DNS/URL health and Linux user-manager state are reported as explicit checks.
CASE STUDY / AUTOMATION RELIABILITY
Automation First Aid.
A diagnostic-only CLI for the first minutes of an automation incident: environment checks, endpoint probing, strict JSON validation, retry-safety classification and Linux user-service status.
THE PROBLEM
A failed automation does not automatically mean “retry it.”
A timeout might be transient. A permission error is probably not. A scary error line can even belong to an earlier attempt while the final process already succeeded. Blind retries can duplicate payments, messages, file writes or other external effects. First response needs enough structure to separate transient failures from configuration errors and already-successful work.
Design constraint
The diagnostic tool must not restart services, rewrite configuration, repair files or replay external actions. It should improve the next decision without creating another side effect.
Observe before acting.
Classify the failure.
Outcomes distinguish successful final state, retry-with-backoff, stop-and-fix, and unknown failures that need review.
Validate the payload.
JSON/JSONL errors surface line and column information, and non-standard NaN/Infinity values are rejected instead of silently accepted.
The boring edge cases are the product.
SUCCESS PRECEDENCE
Exit 0 beats stale error text
If the final process succeeded, the tool returns NO_RETRY even when captured logs still contain timeout or permission-warning text.
HTTP PROBES
HEAD fallback is narrow
GET fallback is used only for 403, 405 or 501 responses that commonly reject HEAD. A genuine 404 stays a failure.
LOG PRIVACY
Probe the real URL, display a safe one
Userinfo and secret-like query values are redacted in output without changing the actual request target.
MALFORMED INPUT
Bad ports do not crash logging
Malformed URL port syntax becomes <invalid-url> rather than escaping the diagnostic boundary.
STRICT EXIT
Human diagnostics can feed CI
--strict-exit maps actionable NG states to exit code 1 while transient retry advice remains non-failing.
SIDE-EFFECT BOUNDARY
No automatic repair
The CLI intentionally stops before remediation, preserving a clean boundary between diagnosis and production changes.
Useful to a human and a monitor.
$ python automation_first_aid.py --strict-exit retry --text "connection reset" --exit-code 1
decision=RETRY_WITH_BACKOFF | reason=transient/network/resource-like error
$ python automation_first_aid.py --strict-exit retry --text "permission denied" --exit-code 1
decision=STOP_AND_FIX | reason=permanent/configuration-like error
exit 1
decision=RETRY_WITH_BACKOFF | reason=transient/network/resource-like error
$ python automation_first_aid.py --strict-exit retry --text "permission denied" --exit-code 1
decision=STOP_AND_FIX | reason=permanent/configuration-like error
exit 1
The same commands can emit JSON, making the tool usable as a lightweight preflight or incident classifier inside a larger monitoring workflow.
Reliability work is mostly decision design.
Idempotency awareness
The retry model starts from the fact that replaying a failed-looking operation may repeat a successful external effect.
Operational observability
Checks return concrete values and classifications rather than collapsing everything into “works” or “broken.”
Safe handoff
Explicit commands, machine-readable output, process exit semantics and tests make the diagnostic behavior reviewable by another operator.
Have a workflow that fails in the ugly 10%?
I can map its failure modes, duplicate risks, retry boundaries and observability gaps before changing production behavior.