TapTap
8141158a3d
New agents: - architect: system design, module interactions, data flow - debugger: crash/memory/thread debugging with ASan, TSan, valgrind, gdb - security-auditor: TLS, input validation, buffer safety, crypto audit - refactorer: DRY, separation of concerns, API simplification - integrator: integration tests, CI/CD pipeline, end-to-end verification - code-explainer: architecture walkthrough, code explanation New skills: - debug-workflow: structured debugging workflow - refactor: code restructuring with test verification - security-audit: full security review with checklist - benchmark: performance benchmarking with multi-run medians - release: version bump, tests, tagging Improved existing: - c-reviewer: added security checklist - cmake-expert: added ASan/TSan/UBSan configs, ccache, cross-compilation - perf-analyst: added perf/valgrind/gprof commands - test-writer: added fuzzing harnesses, integration test patterns - pr-build: added sanitizer build variants - pr-review: added security review, performance impact assessment
139 lines
3.4 KiB
Markdown
139 lines
3.4 KiB
Markdown
---
|
|
name: debug-workflow
|
|
description: 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:
|
|
```bash
|
|
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):**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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):**
|
|
```bash
|
|
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:
|
|
```bash
|
|
gdb --args ./build/client [args...]
|
|
(gdb) run
|
|
# when it crashes:
|
|
(gdb) bt full
|
|
(gdb) info locals
|
|
(gdb) print variable_name
|
|
```
|
|
|
|
For hangs:
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|