Isurwars/Correlation / .agents/skills/diagnosing-bugs
diagnosing-bugs
VerifiedDisciplined debugging and diagnosis loop for hard bugs, compiler errors, linker failures, and runtime regressions. Use when something is broken, throwing, failing, or slow.
Diagnosing Bugs
This skill provides structured diagnostic protocols for interpreting and resolving C++ compilation, linkage, and runtime errors in the Correlation project.
1. Diagnostic Output Format
All error reports must follow the strict format:
[File:Line] -> [Error Category] -> [Root Cause] -> [Fix Action]
Example:
[src/calculators/RDFCalculator.cpp:142] -> Template Instantiation Error ->
Missing `#include <algorithm>` for `std::ranges::sort` ->
Add `#include <algorithm>` to file header
2. Common Error Patterns & Resolution
Compiler Errors (Clang/GCC)
| Error Pattern | Root Cause | Fix |
|---|---|---|
no matching function for call | Wrong argument types or missing overload | Check parameter types, add static_cast or correct overload |
use of undeclared identifier | Missing #include or namespace qualification | Add include or using declaration |
no member named 'X' in 'Y' | Accessing non-existent member or wrong struct type | Verify struct definition in header |
cannot convert 'X' to 'Y' | Implicit narrowing or type mismatch | Use static_cast<Y>(x) or correct the source type |
constexpr variable must be initialized | Missing initializer for constexpr | Provide compile-time constant value |
concept 'X' not satisfied | Template argument doesn't meet concept constraints | Check concept requirements and add missing operations |
Linker Errors
| Error Pattern | Root Cause | Fix |
|---|---|---|
undefined reference to 'X' | Missing target_link_libraries or source file not compiled | Add library to CMake target or include .cpp in sources |
multiple definition of 'X' | Symbol defined in header without inline | Add inline keyword or move definition to .cpp |
undefined symbol: vtable | Missing virtual destructor implementation | Implement virtual ~ClassName() = default; in .cpp |
OpenMP / Concurrency Errors
| Error Pattern | Root Cause | Fix |
|---|---|---|
data race on variable 'X' (TSan) | Shared mutable state without synchronization | Use std::atomic, std::mutex, or OpenMP reduction clause |
false sharing (performance) | Thread-local data on same cache line | Use alignas(64) on thread-local accumulators |
use-after-free in parallel loop | Iterator invalidation or dangling reference | Copy data into thread-local storage before parallel region |
Sanitizer Reports
| Sanitizer | Report Prefix | Action |
|---|---|---|
| ASan | heap-use-after-free, stack-buffer-overflow | Fix lifetime/bounds; replace raw pointers with smart pointers |
| LSan | Detected memory leaks | Ensure RAII wrappers for all allocations |
| UBSan | undefined behavior | Add bounds checks, fix signed overflow, validate pointer alignment |
| TSan | Data race detected | Add synchronization primitives |
3. Diagnostic Workflow
- Capture: Run build command, capture full stderr output.
- Extract: Parse first error only (cascading errors are usually symptoms).
- Classify: Match error text against patterns in tables above.
- Locate: Navigate to exact file and line from error message.
- Fix: Apply the prescribed fix action.
- Verify: Rebuild and confirm error is resolved before proceeding to next error.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |