UC-03: Bug Localization
When a failing test, stack trace, or production symptom needs to be traced to its root cause. Takes a symptom (prose or an error/stack trace) and localizes it through the semantic model (source → branch/condition → offending state or sink), producing a root-cause hypothesis, an evidence table, blast radius, a minimal-fix direction, and where a regression test belongs.
What Makes It Different
- The localization path is reconstructed from the program graph (data-flow tracing, call chains, symbol overviews, source reads) and pinned to the buggy commit, so every step cites file:line rather than pattern-matching.
- It keeps explicit confidence boundaries: it distinguishes what it proved from what it inferred, and does not claim runtime reproduction unless a run actually happened.
Prompt
Run RubberDuck UC-03: Bug Localization. [EDIT INPUTS ONLY] target = <owner/repo or local path> branch = auto commit = latest bug = <describe the bug in prose> [/EDIT INPUTS ONLY] Do not edit the repo; localize root cause and propose patch/tests only. Use prod RubberDuck evidence: `get_started`, completed `detailed_repo_analysis(..., semantic_mode="full")`, Phase 2 ready, `load_code(max_files=4000)`. Stop if a hard RD primitive stays hidden after 3 scoped exposure retries, ref binding fails, or evidence is stale/wrong branch/commit/path. Inspect relevant route/entrypoint, handler, input parse, source, branch condition, sink, safe sibling/contrast path, and missing guard. Validate with source reads plus targeted trace/search/graph/security evidence; no web/raw GitHub or generic fallback evidence. Write `BUG_LOCALIZATION_REPORT.md`: scenario, root-cause hypothesis, evidence table, root cause, blast radius, minimal fix, regression probes, adversarial negative case, method notes. Security artifact contract: include sections named Security Invariant, Adversarial Probes, Impact/Test Matrix, Evidence-Cleanliness Blockers, Unsupported Clean/Security-Ready Claims. Final response starts `RubberDuck initialization: passed` or failure with failed step; name target/ref/scope/output dir and do not claim fixed/clean beyond evidence.
Input
Repo, branch/ref, commit, bug symptom or failing test.
Output
A bug-localization report: root-cause hypothesis, evidence table, blast radius, minimal fix, regression-test location.
The Bug
Codebase: Django 3.0 (2,277-line query.py, the heart of Django's ORM)
Instance: django__django-11062 from the SWE-bench benchmark
Symptom: ExtractHour in annotate+aggregate crashes with ProgrammingError, but the same pattern with F() works fine.
# WORKS:
MyModel.objects.annotate(total=F('usage')).aggregate(avg=Avg('total'))
# CRASHES — ProgrammingError: column "hour" must appear in the GROUP BY clause
MyModel.objects.annotate(hour=ExtractHour('usage_time')).aggregate(avg=Avg('hour'))Root cause: Not 1 bug, but 3 interacting bugs in get_aggregation() and rewrite_cols(): a 120-line algorithm with 4 branches, a FIXME comment, and an annotation_select_mask that is never initialized on the inner query.
With RubberDuck MCP: Found All 3 Bugs, 0 Reversals
load_code(repo="local/django")
1 file loaded (query.py, 2277 lines), code graph built: 10,834 syntax nodes, 2,515 data-flow nodes
query_action(action="trace_variable", analysis_id="your-analysis-id", var="col_cnt")
8 data-flow nodes, lines 355–451. Counter flows through 2 scopes: incremented at 386 (Branch 3 only)
query_action(action="trace_variable", analysis_id="your-analysis-id", var="annotation_select_mask")
13 source matches across 10 functions. KEY: No set_annotation_mask call on inner_query before loop
query_action(action="call_chain", analysis_id="your-analysis-id", method="rewrite_cols")
2 callers + 4 callees. Called by get_aggregation(399) and get_count(488)
query_action(action="control_guards", analysis_id="your-analysis-id", line=383)
No guards found: the 4-branch isinstance check has no surrounding guards
query_action(action="trace_variable", analysis_id="your-analysis-id", var="has_existing_annotations")
3 data-flow nodes. Both uses treat ALL annotations equally: no aggregate vs non-aggregate distinction
query_action(action="trace_variable", analysis_id="your-analysis-id", var="inner_query")
21 data-flow nodes, lines 426–462. Complete mutation history: no set_annotation_mask between creation and loop
search_code(pattern="annotation_select_mask")
13 matches. NEGATIVE PROOF: mask NEVER set on inner_query before line 449
read_source(function_name="rewrite_cols")
43-line function. Branch 3 calls append_annotation_mask (389), Branch 4 does NOT
read_source(function_name="get_aggregation")
88-line function. Full subquery wrapping visible with annotation loop at 449-455
Bugs found (all 3):
- Bug 1:
has_existing_annotationstoo broad (Line 406): treats ALL annotations equally - Bug 2:
annotation_select_masknever set on inner_query (Lines 426-449) - Bug 3: Branch 4 of rewrite_cols doesn't add to mask (Line 391-394)
Result: 0 reversals. 0 test scripts. 3 bugs found. 3-part fix proposed.
Without MCP: Found 1 of 3 Bugs, 2 Wrong Claims
- Found Bug 1 (has_existing_annotations), correct
- Wrong claim: "The issue isn't in rewrite_cols", it IS (Branch 4 missing mask update)
- Wrong claim: "annotation_select_mask is handled correctly at line 455", it's a no-op because mask is None
- Created 3 test scripts, none could run
- Proposed 1-part fix (incomplete: only Bug 1 of 3)
Comparison
| Dimension | With RubberDuck MCP | Without MCP |
|---|---|---|
| Bugs found | 3 of 3 | 1 of 3 |
| Wrong claims | 0 | 2 ("mask handled correctly", "not in rewrite_cols") |
| Test scripts created | 0 | 3 (none could run) |
| Fix completeness | 3-part fix (complete) | 1-part fix (partial) |
| Negative proof | Proved mask NEVER set on inner_query (13 sites scanned) | Claimed mask IS correct |
| Variable tracking | 21 data-flow nodes for inner_query, 8 for col_cnt, all coherence 1.0 | Manual reading of 120-line algorithm |
Videos
With RubberDuck MCP:
Django's 2,277 line query.py is loaded with both RubberDuck MCP servers, rubberduck-codebase-intelligence and rubberduck-semantic-intelligence, showing enabled in Cursor Settings. On the same ExtractHour crash report, the agent runs trace_variable on col_cnt, annotation_select_mask, and inner_query, call_chain on rewrite_cols, and search_code across the file, each call returning data-flow node counts and file and line citations (inner_query mutated at 21 tracked sites between lines 426 and 462). That evidence lets it prove annotation_select_mask is never set on inner_query before line 449, and after all 7 to-dos are checked off it proposes two coordinated fixes, tightening has_existing_annotations and initializing the mask on inner_query, matching the three bug root cause shown above.
Without MCP:
Same query.py bug report, but both MCP servers show Disabled in Cursor Settings. With no graph to query, the agent greps for annotation_select_mask and class F(, reads files like datetime.py and expressions.py, and after exploring 11 files and 4 searches tries to confirm its theory by running python3, only to find the environment isn't fully set up for Django. It ships a single fix to has_existing_annotations and checks it off as 3 of 3 to-dos done, verifying the change with a hand written table of old versus new results on three sample expressions rather than the actual query, so the annotation_select_mask bug in rewrite_cols and inner_query goes uncaught.