troubleshootlisted

# Troubleshoot ## When to use - Invoke for failures, regressions, unclear errors, flaky behavior, broken tests, build issues, runtime faults, or unexpected output. - Execute immediately upon invocation. Don't wait for confirmation. ## Goal - Observe real behavior, test one hypothesis at a time, fix proven root causes, and verify the result. - Identify the root cause with evidence. - Apply the smallest safe fix. - Prove the fix through targeted tests and the strongest relevant check. ## Input Determine input by one of the following: - Issue, symptom, error, failing command, stack trace, or test failure provided by the user. - Current repository state and failing verification when the user gives only a broad troubleshooting request. ## Testing See `references/testing-guide.md` for test structure, isolation, mocking, assertion, and performance standards. ## Shell Commands See `references/shell-command-guide.md` for command safety, timeouts, redirects, and non-interactive environment directives. ## Cleanup See `references/cleanup-guide.md` for the self-introduced-artifact checklist and diff-only audit scope. ## Workflow 1. **GATE**—Require an actionable symptom: error, failure, trace, or incorrect output. Halt and ask if none exists. 2. **ORIENT**—Name the failure and scope in one sentence. State what won't change. 3. **PLAN**—Read `references/shell-command-guide.md`. State one likely root cause and one targeted check to confirm or reject it. 4. **