troubleshoot

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. ACT—Execute:
   • Reproduce the failure.
   • Run the targeted check; on rejection, return to PLAN.
   • After 3 rejections, trace data flow from entry point.
   • Read references/testing-guide.md. Write a failing test reproducing the root cause, when practical.
   • Apply the smallest safe fix after evidence confirms.
5. VERIFY—Loop over every criterion declared in PLAN:
   • Audit the task's own git diff/git status against the Self-cleanup checklist in references/cleanup-guide.md; remove every self-introduced artifact before proceeding.
   • For each unmet criterion: revert the fix, return to ACT, execute, then re-enter VERIFY.
   • Exit only when all criteria pass.
   • Halt only for out-of-scope blockers.
6. PERSIST—Write all fix artifacts once, atomically, after VERIFY passes. Never precedes VERIFY. Never partial.
7. REPORT—Emit the result following the result directives and using the result template.