crash-bisection

Crash Bisection Debugging Command

Systematically isolate the exact line of code causing a crash through methodical bisection (commenting/uncommenting code). This process will ALWAYS succeed if followed precisely.

CRITICAL: Unwavering Methodology

YOU MUST BE ABSOLUTELY STUBBORN AND METHODICAL. DO NOT DEVIATE.

• ❌ DO NOT try to add debug logging (crashes swallow output)
• ❌ DO NOT try to fix the issue until the exact line is found
• ❌ DO NOT skip steps or make assumptions
• ❌ DO NOT re-enable all code if something doesn't work
• ❌ DO NOT report back until the EXACT line is identified
• ✅ DO follow the bisection process EXACTLY as described
• ✅ DO continue methodically even if it seems tedious
• ✅ DO test after EVERY single change

Required Information from User

Ask the user to provide:

1. Test command: The exact command that reproduces the crash (e.g., zig build test-opcodes -Dtest-filter='ADD opcode')
2. File path: The file suspected to contain the crash (or use $ARGUMENTS if provided)
3. Function name (optional): Specific function to start with if known
4. Crash symptoms: What happens (segfault, panic, hang, etc.)

Phase 1: Initial Verification

1. Run the test command to confirm the crash reproduces
2. Note the exact error message or crash behavior
3. You do not need to create a backup of the file, we already use version control for that

Phase 2: Function-Level Bisection

1. Identify all functions in the suspect file

2. Replace function bodies with stubs one by one, testing after each:

   pub fn someFunction(args: Type) ReturnType {
       // [entire function body commented out]
       // Return stub value to keep compilation working:
       return undefined; // or appropriate default/zero value
   }
   

   For error unions: return error.NotImplemented; For optionals: return null; For void: just return For noreturn: unreachable; or @panic("stub");

3. When the crash disappears after stubbing a function, YOU FOUND THE CULPRIT FUNCTION

4. Restore all other functions to their original state

5. Keep only the culprit function for investigation