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

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

1

load_code(repo="local/django")

1 file loaded (query.py, 2277 lines), code graph built: 10,834 syntax nodes, 2,515 data-flow nodes

2

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)

3

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

4

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)

5

query_action(action="control_guards", analysis_id="your-analysis-id", line=383)

No guards found: the 4-branch isinstance check has no surrounding guards

6

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

7

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

8

search_code(pattern="annotation_select_mask")

13 matches. NEGATIVE PROOF: mask NEVER set on inner_query before line 449

9

read_source(function_name="rewrite_cols")

43-line function. Branch 3 calls append_annotation_mask (389), Branch 4 does NOT

10

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_annotations too broad (Line 406): treats ALL annotations equally
  • Bug 2: annotation_select_mask never 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

DimensionWith RubberDuck MCPWithout MCP
Bugs found3 of 31 of 3
Wrong claims02 ("mask handled correctly", "not in rewrite_cols")
Test scripts created03 (none could run)
Fix completeness3-part fix (complete)1-part fix (partial)
Negative proofProved mask NEVER set on inner_query (13 sites scanned)Claimed mask IS correct
Variable tracking21 data-flow nodes for inner_query, 8 for col_cnt, all coherence 1.0Manual 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.