FastSync/.opencode/skills/debug-workflow/SKILL.md

name, description

name	description
debug-workflow	Debugs crashes, memory errors, hangs, and logic bugs in FastSync using structured methodology. Use when the user says "debug X", "fix crash", "investigate failure", "there's a bug", or needs help diagnosing issues.

Debug Workflow Skill

Structured debugging for FastSync: reproduce → isolate → diagnose → fix → verify. This skill CAN edit files, build, and run tests.

Workflow

Step 1: Understand the Problem

Ask or gather:

• What's the symptom? (crash, hang, wrong output, valgrind error)
• What command triggers it?
• Is it deterministic or intermittent?
• What's the environment? (OS, compiler, network conditions)

Step 2: Reproduce

Build with debug info:

rm -rf build
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)

Try to reproduce the issue with the exact command the user provides.

Step 3: Isolate with Sanitizers

Memory errors (first priority):

rm -rf build
cmake -B build -S . \
  -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
cmake --build build -j$(nproc)
./build/tests
# or run the failing command

Thread errors:

rm -rf build
cmake -B build -S . \
  -DCMAKE_C_FLAGS="-fsanitize=thread -g" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
cmake --build build -j$(nproc)
./build/tests

Valgrind (if ASan doesn't find it):

valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes \
  ./build/client --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk

Step 4: GDB Analysis

If the issue is a crash or hang:

gdb --args ./build/client [args...]
(gdb) run
# when it crashes:
(gdb) bt full
(gdb) info locals
(gdb) print variable_name

For hangs:

# In another terminal:
kill -SIGABRT <pid>  # generates core dump
gdb ./build/client core
(gdb) thread apply all bt

Step 5: Read the Code

Read the relevant source files around the crash/failure point. Look for:

• Unchecked return values
• Null pointer dereferences
• Buffer overflows
• Use-after-free
• Race conditions
• Incorrect protocol handling

Step 6: Diagnose Root Cause

Identify the exact file:line and what's wrong. Common patterns:

• send_n_data / receive_n_data return value not checked
• data_destroy() called but pointer still used
• Queue operation without mutex in threaded code
• Partial read/write not handled
• Integer overflow in size calculations

Step 7: Fix

Apply the minimal fix. Don't refactor while debugging — one change at a time.

Step 8: Verify

# Rebuild and test
cmake -B build -S . && cmake --build build -j$(nproc)
./build/tests

# If integration test needed
python3 test.py

# Re-run under sanitizer to confirm fix
rm -rf build
cmake -B build -S . -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
cmake --build build -j$(nproc)
# reproduce the original failing command

Step 9: Report

Print a summary:

=== DEBUG SUMMARY ===
Symptom: <what was happening>
Root cause: <file:line — what's wrong>
Fix: <what was changed>
Verification: <how it was confirmed fixed>

Rules

• DO edit source files to fix issues
• DO rebuild and test after fixes
• DON'T refactor while debugging — minimal changes only
• DON'T change behavior beyond fixing the bug
• PRESERVE existing code style
• ALWAYS verify with ./build/tests after changes