cpp-debugging
Use when a C++ failure involves memory lifetime, undefined behavior, native crashes, or debugger-only state — debug with symbols, sanitizers, and platform-native debuggers before patching symptoms
Install
npx skills add https://github.com/drvoss/everything-copilot-cli/tree/main/skills/development/cpp-debugging
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install drvoss-everything-copilot-cli@llmmart
git clone https://github.com/drvoss/everything-copilot-cli.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole drvoss/everything-copilot-cli collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
C++ Debugging
systematic-debugging gives you the language-neutral method. This skill adds the
native C++ toolchain and runtime techniques that matter once the bug involves
crashes, corrupted memory, UB, or platform-specific debugger state.
When to Use
- A C++ process crashes with a segmentation fault, access violation, or abort
- The bug depends on object lifetime, ownership, or move/copy behavior
- Behavior changes between debug and release builds
- AddressSanitizer, UndefinedBehaviorSanitizer, or a debugger is needed to see the failure clearly
- A native test hangs, deadlocks, or corrupts memory without a clear stack trace
When NOT to Use
| Instead of cpp-debugging | Use |
|---|---|
| You still do not have a stable reproduction or root-cause workflow | systematic-debugging |
| The failure is a build, compile, or link error | fix-build-errors |
| The issue is performance-only, not correctness | performance-optimization |
Prerequisites
- A reproducible failing command, test, or executable
- A debug-capable build with symbols
- Access to the relevant debugger or sanitizer-enabled toolchain
- Enough context to tell whether the bug is runtime, lifetime, concurrency, or build-related
Workflow
1. Rebuild for diagnosis, not speed
Start with a debuggable build before chasing the crash:
# CMake
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug
# Clang/GCC direct build example
clang++ -std=c++20 -g -O0 -Wall -Wextra -Wpedantic main.cpp -o app.exe
Guidelines:
- enable symbols (
-g,/Zi) - reduce or disable optimization while reproducing (
-O0,/Od) - keep warnings enabled
- reproduce with the same inputs that fail in CI or production-like runs
2. Capture the exact failing surface
# Run the failing binary or test under the same conditions each time
ctest --test-dir build --output-on-failure
# Or run the specific executable directly
.\build\app.exe
Record:
- exact command line
- failing input or fixture
- crash signal or exit code
- first bad log line, assertion, or stack frame
3. Inspect runtime state with a native debugger
Use the platform-native debugger your team standardizes on. Common flows:
# GDB
gdb --args .\build\app.exe <args>
# (gdb) run
# (gdb) bt
# (gdb) frame 0
# (gdb) info locals
# (gdb) p suspiciousVariable
# LLDB
lldb -- .\build\app.exe <args>
# (lldb) run
# (lldb) bt
# (lldb) frame variable
Focus on:
- the first frame where state becomes invalid
- moved-from or already-destroyed objects
- container bounds and iterator validity
- null or dangling pointers
- cross-thread ordering when the state only fails under load
4. Turn on sanitizers early
Sanitizers catch the class of bugs that ordinary logging often hides.
# Clang/GCC
cmake -S . -B build-asan `
-DCMAKE_BUILD_TYPE=Debug `
-DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"
cmake --build build-asan
ctest --test-dir build-asan --output-on-failure
If your toolchain supports it, enable the equivalent native flags on Windows as well (for example MSVC AddressSanitizer in supported versions).
Use sanitizer output to answer:
- which access was invalid
- which allocation/free site owned the memory
- whether UB happened before the visible crash
5. Use core dumps or crash artifacts when the bug is post-mortem
If the crash only appears outside the current shell, collect the artifact and inspect it:
- preserve the crashing binary and symbols
- keep the exact build that produced the dump
- load the dump in the matching debugger
- compare the crashing frame with the last known good run
Do not "fix" a crash dump by guessing from the top frame alone. Trace ownership and state backwards.
6. Fix the root cause and harden the boundary
Typical C++ root causes:
- lifetime mismatch between owner and borrower
- invalid iterator or reference after container mutation
- double free or use-after-free
- missing synchronization around shared mutable state
- undefined behavior surfaced by a newer compiler or optimizer
After the fix:
- rerun the failing reproduction
- rerun sanitizer-enabled tests
- add a regression test where practical
- check nearby code for the same lifetime or ownership pattern
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "The debugger changes timing, so it is useless" | Timing-sensitive bugs still need debugger or sanitizer evidence. Use them to narrow the class of failure, then confirm in a normal run. |
| "Release-only crash means the optimizer is broken" | Most release-only failures are UB, data races, or lifetime bugs that debug mode accidentally masks. |
| "The stack trace is enough" | Native crashes often happen far from the real cause. Ownership history matters more than the final frame. |
| "I'll just add null checks" | Null checks do not fix dangling references, iterator invalidation, or races. |
Red Flags
- The crash disappears when you add logging but no root cause is identified
- The only "fix" is changing optimization level
- You cannot say which object owns the failing memory
- The code mixes raw ownership, smart pointers, and borrowed references without clear boundaries
- No regression test or sanitizer rerun happened after the fix
Verification
- A reproducible failing command or test exists
- A debug-symbol build was used during diagnosis
- Debugger or sanitizer output identifies the real failure class
- The final fix addresses ownership, bounds, synchronization, or UB at the source
- The targeted reproduction and relevant tests pass after the fix
Tips
- Prefer smaller reproductions: isolate the failing target or test before debugging the whole system
- If the stack is noisy, break on the first thrown exception, failed assertion, or allocator error
- Compare debug and release compile flags when behavior diverges
- If the bug looks build-related after all, hand off to
fix-build-errors
See Also
systematic-debugging— root-cause method before tool-specific workfix-build-errors— compile, link, and configuration failurestdd-workflow— add regression tests after the runtime bug is fixed
Files (everything-copilot-cli)
-
SKILL.md 6.6 KB
--- name: cpp-debugging license: MIT description: Use when a C++ failure involves memory lifetime, undefined behavior, native crashes, or debugger-only state — debug with symbols, sanitizers, and platform-native debuggers before patching symptoms metadata: category: development agent_type: general-purpose --- # C++ Debugging `systematic-debugging` gives you the language-neutral method. This skill adds the native C++ toolchain and runtime techniques that matter once the bug involves crashes, corrupted memory, UB, or platform-specific debugger state. ## When to Use - A C++ process crashes with a segmentation fault, access violation, or abort - The bug depends on object lifetime, ownership, or move/copy behavior - Behavior changes between debug and release builds - AddressSanitizer, UndefinedBehaviorSanitizer, or a debugger is needed to see the failure clearly - A native test hangs, deadlocks, or corrupts memory without a clear stack trace ## When NOT to Use | Instead of cpp-debugging | Use | |--------------------------|-----| | You still do not have a stable reproduction or root-cause workflow | `systematic-debugging` | | The failure is a build, compile, or link error | `fix-build-errors` | | The issue is performance-only, not correctness | `performance-optimization` | ## Prerequisites - A reproducible failing command, test, or executable - A debug-capable build with symbols - Access to the relevant debugger or sanitizer-enabled toolchain - Enough context to tell whether the bug is runtime, lifetime, concurrency, or build-related ## Workflow ### 1. Rebuild for diagnosis, not speed Start with a debuggable build before chasing the crash: ```powershell # CMake cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build --config Debug # Clang/GCC direct build example clang++ -std=c++20 -g -O0 -Wall -Wextra -Wpedantic main.cpp -o app.exe ``` Guidelines: - enable symbols (`-g`, `/Zi`) - reduce or disable optimization while reproducing (`-O0`, `/Od`) - keep warnings enabled - reproduce with the same inputs that fail in CI or production-like runs ### 2. Capture the exact failing surface ```powershell # Run the failing binary or test under the same conditions each time ctest --test-dir build --output-on-failure # Or run the specific executable directly .\build\app.exe ``` Record: 1. exact command line 2. failing input or fixture 3. crash signal or exit code 4. first bad log line, assertion, or stack frame ### 3. Inspect runtime state with a native debugger Use the platform-native debugger your team standardizes on. Common flows: ```powershell # GDB gdb --args .\build\app.exe <args> # (gdb) run # (gdb) bt # (gdb) frame 0 # (gdb) info locals # (gdb) p suspiciousVariable # LLDB lldb -- .\build\app.exe <args> # (lldb) run # (lldb) bt # (lldb) frame variable ``` Focus on: - the first frame where state becomes invalid - moved-from or already-destroyed objects - container bounds and iterator validity - null or dangling pointers - cross-thread ordering when the state only fails under load ### 4. Turn on sanitizers early Sanitizers catch the class of bugs that ordinary logging often hides. ```powershell # Clang/GCC cmake -S . -B build-asan ` -DCMAKE_BUILD_TYPE=Debug ` -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" cmake --build build-asan ctest --test-dir build-asan --output-on-failure ``` If your toolchain supports it, enable the equivalent native flags on Windows as well (for example MSVC AddressSanitizer in supported versions). Use sanitizer output to answer: - which access was invalid - which allocation/free site owned the memory - whether UB happened before the visible crash ### 5. Use core dumps or crash artifacts when the bug is post-mortem If the crash only appears outside the current shell, collect the artifact and inspect it: ```text - preserve the crashing binary and symbols - keep the exact build that produced the dump - load the dump in the matching debugger - compare the crashing frame with the last known good run ``` Do not "fix" a crash dump by guessing from the top frame alone. Trace ownership and state backwards. ### 6. Fix the root cause and harden the boundary Typical C++ root causes: - lifetime mismatch between owner and borrower - invalid iterator or reference after container mutation - double free or use-after-free - missing synchronization around shared mutable state - undefined behavior surfaced by a newer compiler or optimizer After the fix: - rerun the failing reproduction - rerun sanitizer-enabled tests - add a regression test where practical - check nearby code for the same lifetime or ownership pattern ## Common Rationalizations | Rationalization | Reality | |----------------|---------| | "The debugger changes timing, so it is useless" | Timing-sensitive bugs still need debugger or sanitizer evidence. Use them to narrow the class of failure, then confirm in a normal run. | | "Release-only crash means the optimizer is broken" | Most release-only failures are UB, data races, or lifetime bugs that debug mode accidentally masks. | | "The stack trace is enough" | Native crashes often happen far from the real cause. Ownership history matters more than the final frame. | | "I'll just add null checks" | Null checks do not fix dangling references, iterator invalidation, or races. | ## Red Flags - The crash disappears when you add logging but no root cause is identified - The only "fix" is changing optimization level - You cannot say which object owns the failing memory - The code mixes raw ownership, smart pointers, and borrowed references without clear boundaries - No regression test or sanitizer rerun happened after the fix ## Verification - [ ] A reproducible failing command or test exists - [ ] A debug-symbol build was used during diagnosis - [ ] Debugger or sanitizer output identifies the real failure class - [ ] The final fix addresses ownership, bounds, synchronization, or UB at the source - [ ] The targeted reproduction and relevant tests pass after the fix ## Tips - Prefer smaller reproductions: isolate the failing target or test before debugging the whole system - If the stack is noisy, break on the first thrown exception, failed assertion, or allocator error - Compare debug and release compile flags when behavior diverges - If the bug looks build-related after all, hand off to `fix-build-errors` ## See Also - [`systematic-debugging`](../systematic-debugging/SKILL.md) — root-cause method before tool-specific work - [`fix-build-errors`](../fix-build-errors/SKILL.md) — compile, link, and configuration failures - [`tdd-workflow`](../tdd-workflow/SKILL.md) — add regression tests after the runtime bug is fixed
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.