x-troubleshoot-operations

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Troubleshoot

Purpose

Provides a systematic approach to diagnose and fix issues in {{PROJECT_NAME}}. Covers compilation errors, test failures, build failures, runtime exceptions, and domain-specific bugs.

Triggers

• /x-troubleshoot-operations — diagnose issues using the full debug workflow
• /x-troubleshoot-operations "NullPointerException in PaymentService" — diagnose a specific error
• /x-troubleshoot-operations testMethodName — diagnose a specific test failure

Workflow

1. REPRODUCE  -> Get the exact error (stacktrace, build log, test output)
2. LOCATE     -> Find where the error originates
3. UNDERSTAND -> Why is it failing? Expected vs actual behavior?
4. FIX        -> Write a test that reproduces the bug, then fix the code
5. VERIFY     -> Run the full test suite to ensure no regressions

Always follow this order. Never skip step 4's "write a test first" — the bug-reproducing test prevents regressions.

Step 1 — Reproduce

Get the exact error output. Run the relevant command and capture the full stacktrace, build log, or test output.

{{COMPILE_COMMAND}}

Step 2 — Locate

Find where the error originates using the error patterns below.

2.1 — Compilation Errors

The error patterns below are {{LANGUAGE}}-specific. Adapt to the actual compiler/interpreter messages for the project:

Error Category	Likely Cause	Fix
Missing symbol/type	Missing import, typo in class name	Check package structure, verify imports
Type mismatch	Wrong type in assignment/return	Check type inference, explicit cast if needed
Sealed type error	Missing permits/implementations	Add implementing class to sealed hierarchy
Missing package/module	Wrong package or missing dependency	Verify directory matches package, check deps
Interface mismatch	Signature mismatch with interface	Compare method signature with interface def

2.2 — Test Failures

{{TEST_COMMAND}}

Failure Type	Diagnosis	Fix
Assertion error (expected X got Y)	Logic bug in production code	Compare expected vs actual, trace the logic
NullPointerException in test	Missing setup	Initialize all objects test needs
Test passes alone, fails in suite	Shared mutable state	Ensure fresh objects per test
Timeout in test	Async issue or infinite loop	Check for blocking calls, add timeouts

2.3 — Build Failures

{{BUILD_COMMAND}}

Error	Cause	Fix
Coverage threshold failure	Coverage below threshold	Write more tests, check coverage report
Dependency resolution failure	Missing or conflicting dep	Check build file, resolve conflicts
Out of memory	Memory issue in test/build	Increase memory limits, check for leaks

2.4 — Runtime Errors

The error patterns below are {{LANGUAGE}}-specific. Adapt to the actual runtime error messages for the project:

Error Category	Likely Cause	Fix
Missing class/module at runtime	Missing dependency at runtime	Check classpath/module path, add dependency
Method/function not found	Version mismatch	Align dependency versions
Connection refused	Service not running	Start required services, check ports
Circuit breaker open	Downstream service failure	Check downstream health, wait for recovery

2.5 — Performance Issues

Symptom	Likely Cause	Fix
Slow response	N+1 queries, missing indexes	Add indexes, optimize queries
Memory growing	Object leak, missing cleanup	Profile memory, fix resource management
Thread starvation	Blocking on event loop	Use async patterns, offload to workers

Step 3 — Understand

Analyze why the error occurs. Compare expected vs actual behavior. Trace the data flow from input to the failure point.

Step 4 — Fix (Test-First)

For every bug found:

1. Write a test that reproduces the bug (it MUST FAIL)
2. Fix the code
3. Verify the test PASSES
4. Run full test suite for regressions

// This test was added for bug #NNN
// Previously [describe the bug]

Step 5 — Verify

Run the full test suite. Confirm zero regressions. Check coverage thresholds.

Quick Diagnosis Checklist

When something fails, check in this order:

1. Compilation error? — Read the error message carefully
2. Test failure? — Read expected vs actual, run test in isolation
3. Coverage failure? — Check coverage report, find uncovered branches
4. Dependency issue? — Check build file, verify versions
5. Configuration issue? — Check properties, environment variables
6. Intermittent? — Suspect shared mutable state, race conditions

Error Classification for Group Verifier

When troubleshooting within the feature lifecycle, classify errors for x-lib-verify-group:

Classification	When	Action
TASK_ERROR	Error in current group's code	Retry same tier
MISSING_DEPENDENCY	Missing type from previous group	Halt, flag regression
BUILD_ERROR	Missing external dependency	Halt, fix build file
UNKNOWN	Unrecognized error pattern	Escalate tier

Error Handling

Scenario	Action
Stacktrace not available	Request the user to provide the full error output
Error in third-party library	Verify dependency versions, check for known issues upstream
Non-reproducible failure	Investigate shared mutable state, race conditions, or environment differences
Fix introduces new failures	Revert the fix, re-analyze root cause with broader context

Integration Notes

Skill	Relationship	Context
x-lib-verify-group	Referenced by	Invokes troubleshoot when compilation fails during group verification
x-implement-story	Referenced by	Used during Phase 4 (fixes) for diagnosing test and build failures
x-execute-tests	Complements	Troubleshoot diagnoses failures that x-execute-tests reports