Recap — Sharing Context, Narrowing the Problem

# Sharing Context, Narrowing the Problem Debugging with AI is one of the highest-leverage activities. But "fix this bug" rarely works. The patterns that do. ## The structure of a good debug prompt Three components: ### 1. What you observed Specific behavior: input, expected, actual. > "I'm calling process_order(order_id=42) and getting None. The order exists in DB. Expected: the processed order dict." ### 2. What you've already tried Save AI from suggesting things you've ruled out. > "I already verified the order exists in the DB. I added print statements; the function enters but returns None at the end. The 'total' calculation seems wrong." ### 3. What you suspect (if anything) Direct AI toward likely areas. > "I think the bug is in calculate_total — it returns 0 when it should return the sum. But I'm not sure why." ## Bad debug prompts Bad: > "Why doesn't this work?" AI guesses generically; usually wrong. Bad: > "This is broken. Fix it." No context. AI fumbles. Bad: > "I get an error: TypeError: 'int' object is not iterable. Help!" Better than nothing, but missing the code and stack trace. ## Good debug prompts Good: > "This function should sum the prices of items in an order. Input: order with items=[{'price': 10}, {'price': 20}]. Expected: 30. Actual: TypeError 'int' object is not iterable on line `for item in order_items:`. > > [code paste] > > Walk through what happens; tell me what's wrong and how to fix." AI now has: - The behavior contract. - The input. - The error and location. - The code itself. - Direction (analyze step by step). ## Pasting context For tricky bugs, paste: - The function with the bug. - The caller. - The exception with stack trace. - Relevant data (one row from DB, sample input). - Tests if available. Big context dump. AI sorts through. In Cursor / Claude Code: just have the relevant files open / mentioned; AI reads. ## The "narrow it down" pattern Don't ask AI to find the bug in 1000 lines. Narrow first. Steps: 1. Identify the smallest reproduction. 2. Strip to relevant code. 3. Paste into AI with the symptom. ```python # Bad: 500 lines of business logic; bug somewhere def big_complex_function(...): # ... # Narrow: 30 lines you've identified def suspicious_subfunction(items): # bug is in here ``` AI works much better on focused inputs. ## "Walk through this code" technique For tricky logic: > "Walk through this code line by line with input X. Tell me the value of each variable at each step. Identify where it diverges from expected behavior." AI traces execution. Often catches things you'd miss. ## "What are possible causes" technique When you don't know where to look: > "I'm seeing: [symptom]. What are 5 possible causes? Rank by likelihood." AI brainstorms; you investigate each. ## "Add logging to narrow it down" technique > "Add logging to this function to help me find where it goes wrong. Cover: entry args; values at each major step; exit value." AI adds prints/logging. You run; logs reveal the issue. ## When AI suggests something wrong Don't immediately accept "the bug is X" without checking. AI is often confidently wrong on tricky bugs. Reasonable-sounding suggestions that aren't right. Verify each suggestion: - "Does this match the symptom I observed?" - "Can I reproduce with a minimal example?" If AI's hypothesis doesn't fit the data, push back: > "That doesn't explain why X happens. What else might cause this?" ## The "rubber duck" effect Sometimes describing the bug carefully causes you to find it yourself. Writing out: - What I expected. - What actually happened. - What I've tried. Often reveals the answer mid-typing. AI as forced rubber duck. Underrated. ## Bug categories and patterns ### Off-by-one Symptoms: misses first or last element; wrong count. Common: range(), slicing, loop bounds. ### Wrong condition Symptoms: behavior right sometimes, wrong other times. Common: `or` vs `and`, `<` vs `<=`, negation. ### State leak Symptoms: works first time; fails on second run (test interference). Common: shared mutable default args, class-level state, global vars. ### Race condition Symptoms: bug appears intermittently; hard to reproduce. Common: async without await, threading without locks, time-based logic. ### Type confusion Symptoms: TypeError or unexpected None. Common: API returns None or unexpected type; not handled. ### Encoding Symptoms: unicode errors; weird character display. Common: file reading without explicit encoding, byte vs str mismatch. Knowing these patterns helps direct AI: "This is probably a race condition; look for missing await." ## The minimal reproduction For really tricky bugs, build a minimal reproduction: ```python # minimal_repro.py def buggy_function(x): # the suspected code, isolated return x * 2 # but actually returns 0 assert buggy_function(5) == 10 # fails ``` Then share with AI. Once minimal, AI usually finds the issue. ## When AI can't help Some bugs