Agent Skills: Qt C++ Bug Fixer

Qt C++ Bug Fixer

Overview

Diagnose and fix Qt C++ bugs with minimal, Qt-style changes. Iron Rule: Fix ONLY the reported issue. No extra refactoring, no "while I'm here" improvements.

When to Use

Compilation Errors: undefined reference to 'vtable', missing Q_OBJECT, MOC errors, circular includes, CMakeLists.txt/.pro issues

Runtime Crashes: Segmentation faults, null pointer dereferences, pure virtual calls

Memory Issues: new without delete, incorrect parent-child relationships, leaks

UI Problems: Widgets not displaying, layout failures, signal-slot not working, unresponsive controls

Threading: Cross-thread UI crashes, thread affinity, blocking UI thread

Do NOT use when: Intentionally refactoring, adding features (use TDD), or performance optimization

Core Pattern

// ❌ WRONG: Refactoring while fixing
void MyWidget::processData()
{
    if (m_processor) {
        auto dataProcessor = m_processor;  // UNNECESSARY rename
        QList<int> items = dataProcessor->getItems();  // UNNECESSARY STL→Qt
        qDebug() << "Processing" << items.size();  // UNNECESSARY logging
    }
}

// ✅ CORRECT: Only the fix
void MyWidget::processData()
{
    if (m_processor) {  // Fix: Added null check
        m_processor->process();
    }
}

// ❌ WRONG: External smart pointers
#include <memory>
std::unique_ptr<DataProcessor> m_processor;

// ✅ CORRECT: Qt parent-child ownership
DataProcessor *m_processor = new DataProcessor(this);  // Parent handles deletion

Quick Reference

| Bug Type | Root Cause | Minimal Fix | |----------|------------|-------------| | undefined reference to 'vtable' | Missing Q_OBJECT macro | Uncomment/add Q_OBJECT in header | | moc file not generated | Header not in CMakeLists.txt/.pro | Add header to build files | | Segfault on nullptr | No null check before dereferencing | Add if (ptr) before use | | Memory leak | new without parent ownership | Add parent to new or use deleteLater() | | Signal not firing | Connection broken or wrong signature | Check connect() syntax and lifetime | | Cross-thread UI crash | Direct UI manipulation from worker | Use QMetaObject::invokeMethod or signal-slot |

Implementation

1. Diagnostic Phase

Read error carefully: Compiler error → find line number; Runtime crash → read backtrace; UI issue → note specific behavior

Locate problematic code: Use @file:line notation, read context (class definition, includes, parent), check related files

Check Qt context: Does class inherit QObject? Is Q_OBJECT present? Are parent-child relationships correct? Are signals/slots connected?

2. Hypothesis and Verification

Generate 1-2 root causes: Focus on error type (MOC/config, memory/null, signals/layout, thread affinity)

Verify hypothesis: Check code - don't assume. MOC errors always involve Q_OBJECT and meta-object system

3. Generate Minimal Fix

Fix ONLY the identified issue: ONE problem = ONE fix. No variable renames, no style cleanup, no optimizations

Explain WHY: Root cause, not symptom. Qt-specific mechanics (MOC, parent-child, signal-slot)

Explain HOW: Principle behind change. Why it solves root cause

Regression testing: Compile (cmake --build . or make), suggest specific verification steps, run tests if applicable

4. Configuration File Fixes

CMakeLists.txt:

qt_add_executable(MyApp
    main.cpp
    mywidget.h  # MUST include header with Q_OBJECT
    mywidget.cpp
)

.pro file:

HEADERS += mywidget.h  # Headers with Q_OBJECT must be listed
SOURCES += mywidget.cpp

Common Mistakes

| Mistake | Why Wrong | Correct | |---------|-----------|---------| | Renaming variables while fixing | Violates minimal change principle | Keep existing names | | "Upgrading" SIGNAL/SLOT to lambda | Unnecessary change, breaks code | Fix only broken connection | | Converting STL to Qt containers | Unrelated to bug | Fix only what causes crash | | Adding logging "for debugging" | Extra code not needed | Fix root cause directly | | Adding null checks everywhere | Masks real problem | Add only where crash occurs | | Refactoring while fixing | Scope creep, introduces bugs | ONE fix per bug report |

Rationalization Table

| Excuse | Reality | |--------|---------| | "This variable name is confusing, I'll rename it" | Variable names don't cause crashes. Fix the crash. | | "While I'm here, let me upgrade to modern Qt syntax" | Technical debt is not a bug. Fix the bug. | | "This cleanup makes the code clearer" | Clarity improvements are refactoring, not bug fixing. | | "The old SIGNAL/SLOT macros are deprecated" | Deprecated ≠ broken. Fix only what's broken. | | "I'm adding a safeguard, it's defensive programming" | Safeguards without justification are extra code. Fix root cause. | | "This refactoring is minimal and obvious" | Any change beyond the fix is NOT minimal. | | "I'll improve the design while fixing it" | Design improvements are separate tasks. Fix the bug. | | "It's about quality, not just functionality" | Quality bug fixes focus on minimal, surgical changes. |

Red Flags - STOP and Start Over

STOP immediately if you think or say ANY of these:

• "While I'm fixing this, I'll also..."
• "This is a good opportunity to clean up..."
• "The old style should be modernized..."
• "I'll add a safeguard/precaution..."
• "This variable name is confusing, better rename it..."
• "Let me upgrade to the latest Qt API..."
• "This design could be improved..."
• "I'll make it more robust/defensive..."
• "This code is messy, let me organize it..."

ALL mean: You're doing MORE than fixing the bug. Stop. Delete extra changes. Fix ONLY the reported issue.

Qt-Specific Anti-Patterns

Avoid External Smart Pointers:

// ❌ std::unique_ptr
std::unique_ptr<QWidget> m_widget;
// ✅ Qt parent-child
QWidget *m_widget = new QWidget(this);

Thread-Aware Connections:

// ❌ Wrong affinity assumption
workerThread->start();
worker->doWork();  // Might crash
// ✅ Qt 5 explicit type
connect(worker, &Worker::finished, this, [this]() {}, Qt::QueuedConnection);

Qt Blocking Helpers:

// ❌ Manual locks
QMutexLocker locker(&m_mutex);
// ✅ Qt's QSignalBlocker
QSignalBlocker blocker(this);  // Auto-unblocks on scope exit

Memory Management:

// ❌ Manual delete
MyWidget *w = new MyWidget();
delete w;
// ✅ Parent-child system
MyWidget *w = new MyWidget(this);  // Parent deletes on destruction

Backward Compatibility

CRITICAL: Verify fix doesn't break existing connections:

1. Check all connect() calls to/from modified object
2. Verify object lifetime doesn't break parents/children
3. Don't change signal/slot signatures unless that's the bug
4. Don't remove connections unless causing the issue

The Iron Law

Fixing bugs is NOT an excuse for refactoring.

Every change beyond the minimal fix introduces new risk, wastes user's time, violates the contract of "bug fix."

When in doubt: Ask yourself "Would this change be justified if I only said I was fixing the bug, not 'cleaning up'?"

If NO → Delete the change. Fix ONLY the bug.

No exceptions:

• Not for "obvious" improvements
• Not for "technical debt" reduction
• Not for "best practices" alignment
• Not for "making it clearer"
• Not for "while I'm here"
• Minimal fix means MINIMAL