Skip to content

Isurwars/Correlation / .agents/skills/diagnosing-bugs

diagnosing-bugs

Verified

Disciplined 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 PatternRoot CauseFix
no matching function for callWrong argument types or missing overloadCheck parameter types, add static_cast or correct overload
use of undeclared identifierMissing #include or namespace qualificationAdd include or using declaration
no member named 'X' in 'Y'Accessing non-existent member or wrong struct typeVerify struct definition in header
cannot convert 'X' to 'Y'Implicit narrowing or type mismatchUse static_cast<Y>(x) or correct the source type
constexpr variable must be initializedMissing initializer for constexprProvide compile-time constant value
concept 'X' not satisfiedTemplate argument doesn't meet concept constraintsCheck concept requirements and add missing operations

Linker Errors

Error PatternRoot CauseFix
undefined reference to 'X'Missing target_link_libraries or source file not compiledAdd library to CMake target or include .cpp in sources
multiple definition of 'X'Symbol defined in header without inlineAdd inline keyword or move definition to .cpp
undefined symbol: vtableMissing virtual destructor implementationImplement virtual ~ClassName() = default; in .cpp

OpenMP / Concurrency Errors

Error PatternRoot CauseFix
data race on variable 'X' (TSan)Shared mutable state without synchronizationUse std::atomic, std::mutex, or OpenMP reduction clause
false sharing (performance)Thread-local data on same cache lineUse alignas(64) on thread-local accumulators
use-after-free in parallel loopIterator invalidation or dangling referenceCopy data into thread-local storage before parallel region

Sanitizer Reports

SanitizerReport PrefixAction
ASanheap-use-after-free, stack-buffer-overflowFix lifetime/bounds; replace raw pointers with smart pointers
LSanDetected memory leaksEnsure RAII wrappers for all allocations
UBSanundefined behaviorAdd bounds checks, fix signed overflow, validate pointer alignment
TSanData race detectedAdd synchronization primitives

3. Diagnostic Workflow

  1. Capture: Run build command, capture full stderr output.
  2. Extract: Parse first error only (cascading errors are usually symptoms).
  3. Classify: Match error text against patterns in tables above.
  4. Locate: Navigate to exact file and line from error message.
  5. Fix: Apply the prescribed fix action.
  6. Verify: Rebuild and confirm error is resolved before proceeding to next error.
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall