troubleshooting.adoc

Troubleshooting — robodog-ecm

This file is a living FAQ — known failure modes and recovery paths. Add a new entry every time you debug something that took more than 15 minutes; future-you (and other maintainers) will thank you.

Known failure modes

<error message or symptom>

Symptom: short reproduction. What does the user see?

Cause: root cause (one or two sentences).

Fix:

<the actual commands to recover>

Avoidance: how to not hit this again (config setting, doc link, etc.).

---

<another failure mode>

(Replace this and the above example with real entries as you encounter them.)

Diagnostic toolkit

When something is wrong, run these first:

just doctor          # runs all available self-checks
just version         # prints the version & build hash
just log-tail        # last N lines of logs

When to escalate

1. Filed an issue with: version, OS, exact command, full error output, and the symptom in plain English.

2. Linked from the issue: the relevant ADR(s) and any related issues.

3. For security-relevant findings, see SECURITY.md — do not file public issues.

Where to look for more help

• docs/architecture.adoc — internals.

• docs/decisions/ — historical record of why things are this shape.

• https://github.com/hyperpolymath/robodog-ecm/issues?q=is%3Aissue+<your symptom> — has anyone hit this before?

• https://github.com/hyperpolymath/standards/issues — for estate-wide problems.