Systematic Debugging Skill - Demonstrations

This repository contains three realistic debugging scenarios that demonstrate the systematic-debugging skill for Manus AI agents.

Overview

The systematic-debugging skill teaches a four-phase process for debugging:

1. Phase 1: Root Cause Investigation - Understand WHAT and WHY before fixing
2. Phase 2: Pattern Analysis - Find working examples and identify differences
3. Phase 3: Hypothesis and Testing - Form theories and test minimally
4. Phase 4: Implementation - Create tests, fix root cause, verify

The Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Demonstrations

Demo 1: API Integration Bug (Multi-Component System)

File: demo1_api_integration.py

Scenario: Payment processing fails silently in production with generic error message.

Bug Type: Missing environment variable validation in multi-component system

Key Lessons:

• Multi-component systems require diagnostic instrumentation at each layer
• Tracing data flow reveals where bad values originate
• Pattern analysis shows working examples validate env vars at initialization
• Single minimal fix (env var validation) solves the root cause

Run:

python3 demo1_api_integration.py

Expected Output:

{
  "success": false,
  "error": "Payment failed"
}

Demo 2: Test Failure After Refactoring

File: demo2_test_failure.py

Scenario: Tests pass individually but fail when run together with inconsistent assertion errors.

Bug Type: Shared state due to class variable instead of instance variable

Key Lessons:

• Test failures that depend on execution order indicate shared state
• Checking recent changes (git diff) immediately reveals refactoring mistakes
• Pattern analysis shows difference between class and instance variables
• Single line change (moving variable to __init__) fixes the root cause

Run:

python3 demo2_test_failure.py

Expected Output:

✓ Test 1 passed: Single item
✓ Test 2 passed: Multiple items
✓ Test 3 passed: Empty cart
✓ Test 4 passed: Clear cart

[Then failures when run together]
AssertionError: 3 != 1
AssertionError: 4 != 0

Demo 3: Performance Problem (Architectural Issue)

File: demo3_performance.py

Scenario: Dashboard loads in 5-10 seconds instead of < 500ms. Three previous fix attempts (caching, reducing limits, adding indexes) provided minimal improvement.

Bug Type: Architectural problem - N+1 queries, synchronous loading, real-time expensive computation

Key Lessons:

• After 3 failed fixes, question the architecture (don't attempt fix #4)
• Query instrumentation reveals N+1 query patterns
• Symptom fixes (caching, indexes) don't solve architectural problems
• Proper architecture (batch queries, pre-computation) solves root cause

Run:

python3 demo3_performance.py

Expected Output:

============================================================
Testing Dashboard Performance
============================================================
Dashboard loaded in 8.73s
Total queries executed: ~150+
Load time: 8.73s

Expected: < 500ms
Actual: 5-10 seconds

⚠️  After 3 fix attempts, this indicates an architectural problem
    Need to refactor to: batch queries, async loading, pre-computed data

Complete Walkthrough

See DEBUGGING_WALKTHROUGH.md for detailed step-by-step walkthroughs of all three demos, including:

• Complete investigation process for each phase
• Diagnostic instrumentation examples
• Root cause identification
• Pattern analysis
• Hypothesis formation and testing
• Proper fixes with verification

Key Takeaways

The Iron Law Works

All three demos show that jumping to fixes without investigation wastes time:

• Demo 1: Could have added retry logic (wrong) instead of fixing missing env var validation (right)
• Demo 2: Could have added tearDown cleanup (wrong) instead of fixing class variable (right)
• Demo 3: Could have tried 10 more band-aids (wrong) instead of refactoring architecture (right)

Time Savings

Systematic approach:

• Demo 1: 15 minutes to fix
• Demo 2: 10 minutes to fix
• Demo 3: 1 hour to fix properly (after recognizing architectural issue)

Random fixes approach (estimated):

• Demo 1: 1-2 hours of trying different error handling
• Demo 2: 2-3 hours of debugging test isolation
• Demo 3: Days of trying different band-aids, never solving the real problem

First-time fix rate: 100% (3/3 demos fixed correctly on first attempt after investigation)

Red Flags to Watch For

If you catch yourself thinking:

• ❌ "Quick fix for now, investigate later"
• ❌ "Just try changing X and see if it works"
• ❌ "Add multiple changes, run tests"
• ❌ "Skip the test, I'll manually verify"
• ❌ "One more fix attempt" (when already tried 2+)

ALL of these mean: STOP. Return to Phase 1.

Using the Skill

1. Read the skill: /home/ubuntu/skills/systematic-debugging/SKILL.md

2. When you encounter a bug: STOP and follow the four phases

3. Watch for red flags: If you want to "just try a quick fix", return to Phase 1

4. After 3 failed fixes: Question the architecture, don't attempt fix #4

5. Trust the process: Systematic debugging is faster than guess-and-check

Files

• demo1_api_integration.py - API integration bug with multi-component system
• demo2_test_failure.py - Test failure due to shared state
• demo3_performance.py - Performance problem requiring architectural refactor
• DEBUGGING_WALKTHROUGH.md - Complete step-by-step walkthroughs
• README.md - This file

License

These demonstrations are provided as educational examples for the Manus systematic-debugging skill.

---

Remember: The skill saves time by preventing wasted effort on wrong fixes. Use it every time you encounter a bug.