Build 4 — Debug a Tricky Bug with AI

# Build 4 — Debug a Tricky Bug with AI > 🎯 **Hands-on Portfolio Deliverable:** Execute a structured AI-assisted root cause analysis on non-deterministic and logic bugs, refactor the code for testability, and author rock-solid regression tests. --- ## The brief Practice the structured debug-with-AI workflow on a non-trivial bug. Find the bug, fix it, write a regression test. ## The bug Use one of: - A real bug from your work or open-source. - We provide a sample buggy script. For practice, we'll use a sample: ```python # buggy.py from datetime import datetime, timedelta from collections import defaultdict def aggregate_clicks(clicks: list[dict]) -> dict[str, int]: """Aggregate click counts per URL for the LAST 24 HOURS only.""" cutoff = datetime.utcnow() - timedelta(hours=24) counts = defaultdict(int) for click in clicks: if click['timestamp'] > cutoff: counts[click['url']] += 1 return dict(counts) # Test it clicks = [ {"url": "/home", "timestamp": datetime(2026, 5, 27, 10, 0)}, {"url": "/about", "timestamp": datetime(2026, 5, 27, 9, 0)}, {"url": "/home", "timestamp": datetime(2026, 5, 25, 10, 0)}, ] result = aggregate_clicks(clicks) print(result) # Expected: {"/home": 1, "/about": 1} (last 24h only) # Actual: depends on when you run; might be {} or different ``` ## Step 1: Reproduce (10 min) Run the code. Observe: > "I expect {'/home': 1, '/about': 1} (last 24h of 2026-05-27 12:00). I got {}." Document the bug clearly. ## Step 2: Discuss with AI (15 min) > "Here's a bug. I have aggregate_clicks that should return clicks in the last 24h. With these inputs [paste], I expected X, got Y. Current time when running was 2026-05-27 12:00. The function uses datetime.utcnow() for cutoff. Walk through what happens for each click; identify the bug." AI walks through: - cutoff = 2026-05-26 12:00. - click 1 at 10am 5/27: timestamp > cutoff → include. ✓ - click 2 at 9am 5/27: timestamp > cutoff → include. ✓ - click 3 at 10am 5/25: timestamp > cutoff → false; skip. ✓ But wait — output is {}? AI: "The result depends on when the code is RUN. If you run after May 28, the May 27 clicks are too old." Insight: the function's behavior depends on system clock; testing it is hard. ## Step 3: Identify root cause (10 min) > "The bug isn't logic — it's that the function uses datetime.utcnow() inside. That makes it untestable and time-dependent. How should I refactor?" AI suggests: - Accept a `now` parameter (with default of datetime.utcnow()): ```python def aggregate_clicks(clicks: list[dict], now: datetime | None = None) -> dict[str, int]: if now is None: now = datetime.utcnow() cutoff = now - timedelta(hours=24) # ... ``` Now testable. ## Step 4: Write a regression test (10 min) > "Write a pytest test that exercises this with a fixed `now` so it's deterministic. Use the example data." ```python def test_aggregate_clicks_24h_window(): clicks = [ {"url": "/home", "timestamp": datetime(2026, 5, 27, 10, 0)}, {"url": "/about", "timestamp": datetime(2026, 5, 27, 9, 0)}, {"url": "/home", "timestamp": datetime(2026, 5, 25, 10, 0)}, ] now = datetime(2026, 5, 27, 12, 0) result = aggregate_clicks(clicks, now=now) assert result == {"/home": 1, "/about": 1} ``` Test passes. Behavior locked. ## Step 5: Document ```markdown # Bug Report ## Symptom aggregate_clicks returned {} when expected {"/home": 1, "/about": 1}. ## Root cause The function used `datetime.utcnow()` internally. The result depended on when the code ran, making the function: - Time-dependent (output changes by clock). - Hard to test (must control the clock). ## Fix Accept `now` parameter (defaults to datetime.utcnow()). Tests pass a fixed now. ## Regression test test_aggregate_clicks_24h_window ``` ## More debug exercises Apply the same workflow to: ### Exercise A: Off-by-one ```python def get_page(items: list, page: int, page_size: int = 10) -> list: start = page * page_size end = start + page_size return items[start:end + 1] # bug: extra item ``` Bug: returns 11 items, not 10. ### Exercise B: Wrong operator ```python def is_admin_or_owner(user, resource) -> bool: return user.is_admin or user.id == resource.owner_id and user.is_active # bug: precedence; `is_active` only checked on owner, not admin ``` Bug: admin without is_active still passes. ### Exercise C: Edge case ```python def average(nums: list[float]) -> float: return sum(nums) / len(nums) # bug: empty list = ZeroDivisionError ``` Bug: empty input crashes. For each: reproduce → discuss with AI → identify → fix → test. ## Deliverables - Each bug reproduced and fixed. - Regression test per bug. - A `DEBUG.md` documenting: - The original bug behavior. - Steps to reproduce. - Root cause. - Fix. - How AI helped (or didn't). ## What you'll learn - Structured debug-with-AI workflow. - The importance of reproduction. - Identif