GraphLocator: Graph-guided Causal Reasoning for Issue Localization

Abstract: The issue localization task aims to identify the locations in a software repository that requires modification given a natural language issue description. This task is fundamental yet challenging in automated software engineering due to the semantic gap between issue description and source code implementation. This gap manifests as two mismatches:(1) symptom-to-cause mismatches, where descriptions do not explicitly reveal underlying root causes; (2) one-to-many mismatches, where a single issue corresponds to multiple interdependent code entities. To address these two mismatches, we propose GraphLocator, an approach that mitigates symptom-to-cause mismatches through causal structure discovering and resolves one-to-many mismatches via dynamic issue disentangling. The key artifact is the causal issue graph (CIG), in which vertices represent discovered sub-issues along with their associated code entities, and edges encode the causal dependencies between them. The workflow of GraphLocator consists of two phases: symptom vertices locating and dynamic CIG discovering; it first identifies symptom locations on the repository graph, then dynamically expands the CIG by iteratively reasoning over neighboring vertices. Experiments on three real-world datasets demonstrates the effectiveness of GraphLocator: (1) Compared with baselines, GraphLocator achieves more accurate localization with average improvements of +19.49% in function-level recall and +11.89% in precision. (2) GraphLocator outperforms baselines on both symptom-to-cause and one-to-many mismatch scenarios, achieving recall improvement of +16.44% and +19.18%, precision improvement of +7.78% and +13.23%, respectively. (3) The CIG generated by GraphLocator yields the highest relative improvement, resulting in a 28.74% increase in performance on downstream resolving task.

• The paper introduces GraphLocator, a novel framework that leverages LLM-powered causal reasoning to map natural language issue reports to specific code regions.
• The paper employs the Repository Dependency Fractal Structure (RDFS) and dynamic Causal Issue Graph (CIG) expansion to trace multi-hop causal paths, achieving notable recall and precision improvements.
• The paper demonstrates that integrating causal graph discovery reduces false positives and LLM token consumption, leading to more robust and cost-effective issue resolution.

GraphLocator: Graph-guided Causal Reasoning for Issue Localization

Problem Context and Motivation

Automated issue localization—the mapping of natural language issue descriptions to concrete code regions requiring modification—remains a formidable challenge in software engineering. Recent benchmarks reveal that even advanced LLM-based frameworks fail to accurately localize target files in over half of real-world cases. The crux of this difficulty lies in the semantic gap: issue descriptions typically reference high-level symptoms or desired outcomes, often omitting the underlying root cause and the full scope of affected code entities. This deep semantic gap manifests in two critical mismatches:

• Symptom-to-Cause Mismatch: The issue description references observable symptoms, not the true cause, necessitating tracing implicit, multi-hop causal paths through the codebase.
• One-to-Many Mismatch: Resolution may require coordinated changes spanning multiple, interdependent code entities, rather than a single code location.

This dual mismatch substantially impedes existing localization techniques, both embedding-based and agentic LLM-based. Embedding methods achieve high recall via semantic similarity but lack structural and causal awareness, yielding low precision. Agentic methods, while flexible, often fail to maintain coherent causal reasoning over multi-step traversals.

Figure 1: Two core mismatches in issue localization: (a) symptom-to-cause, where the description omits the root cause; and (b) one-to-many, where resolution spans multiple interdependent entities.

GraphLocator Architecture

GraphLocator introduces a graph-guided, LLM-powered localization framework designed to overcome these fundamental mismatches by explicitly modeling causal relationships between symptoms and code via a novel Causal Issue Graph (CIG). The approach leverages a domain-specific graph representation—the Repository Dependency Fractal Structure (RDFS)—and constructs a CIG in an iterative, expansion-based manner:

• Symptom Vertices Locating: GraphLocator first deploys an agentic LLM workflow to identify RDFS vertices (code entities) that directly embody the symptoms described in the issue report. A layer- and type-aware toolset, comprising search_vertex and search_edge operations, facilitates precise mapping between unstructured NL descriptions and code graph nodes.

  Figure 2: The Repository Dependency Fractal Structure (RDFS) encoding multi-layer hierarchical and dependency relations in source code.

• Dynamic CIG Discovering: Initialization from symptom vertices, GraphLocator then incrementally constructs a CIG—a directed graph whose vertices represent discovered sub-issues grounded to RDFS code entities and whose edges encode LLM-estimated causal probabilities between sub-issues. GraphLocator applies priority-driven expansion, selecting sub-issues maximizing causal influence scores, and employs graph-executable abductive reasoning to iteratively discover new sub-issues and update causal dependencies.

  Figure 3: CIG for issue astropy__astropy-12907: nodes encode sub-issues, edges capture probabilistic causal dependencies across code entities.

  

  Figure 4: Workflow of GraphLocator, integrating symptom locating and recursive CIG discovery for granular localization.

Experimental Evaluation

GraphLocator is comprehensively evaluated across three benchmarks—SWE-bench Lite (Python), LocBench (Python), and Multi-SWE-bench (Java)—each containing hundreds of annotated real-world issues. Localization performance is measured at file, module, and function granularities using metrics for success rate, recall, precision, and F1.

Numerical Results

GraphLocator demonstrates robust improvements over representative embedding-based (SWERank-Large, SWERank-Small) and LLM-based (Agentless, LocAgent, CoSIL) baselines:

• Function-level Recall and Precision: Achieves average improvements of +19.49% in recall and +11.89% in precision (Claude-3.5) over best baseline across datasets.
• Mismatch Scenarios: Delivers recall gains of +16.44% (symptom-to-cause) and +19.18% (one-to-many), and precision gains of +7.78% and +13.23%, respectively.
• Downstream Resolving: Integration of CIG-structured localization boosts downstream issue resolution rates by 28.74%.

  Figure 5: Comparative performance of localization approaches on mismatch scenarios (averaged across SWE-bench Lite, LocBench, Multi-SWE-bench Java using Claude-3.5).

GraphLocator consistently balances recall and precision, particularly for complex multi-function or high symptom-to-cause distance instances, where baseline methods experience severe performance degradation.

Figure 6: GraphLocator maintains superior function-level performance as symptom-to-cause distance increases, indicating causal tracing robustness.

Ablation and Cost Analysis

Ablation demonstrates the necessity of each architectural component: removal of either search tool, priority queue, or CIG-guided prompts causes precipitous drops in F1 and recall. GraphLocator achieves efficient graph construction—especially for large repositories via lazy dependency loading—and substantially reduces LLM token consumption compared to agentic alternatives (e.g., LocAgent), improving cost-effectiveness.

Figure 7: Time efficiency comparison: GraphLocator versus LocAgent across repository sizes and function counts.

Implications and Future Directions

GraphLocator's graph-guided, causal reasoning framework sets a foundation for more accurate and interpretable software issue localization. The approach offers the following implications:

• Practical Impact: Substantial reductions in false positives (over-localization) and enhanced handling of complex, multi-entity issues can directly improve developer productivity and reliability of automated repair systems.
• Theoretical Advancement: Explicit modeling of causal sub-issue structures and dynamic disentangling provides a blueprint for integrating structural causal models with LLM-based autonomous agents for code analysis.
• Extensibility: GraphLocator is language-agnostic, requiring only AST-to-RDFS conversion for new programming languages; future enhancements may incorporate richer code semantics, dynamic analysis traces, or advanced graph neural reasoning atop the CIG.
• Broader AI Reasoning: The causal graph discovery approach generalizes to domains requiring reasoning over structural, multi-hop causal dependencies in NL-structured problem descriptions.

Conclusion

GraphLocator advances the state-of-the-art in automated issue localization by bridging the gap between high-level natural language symptoms and complex code dependencies. Through causal structure discovery and dynamic issue disentangling, it achieves robust, fine-grained localization performance, particularly on tasks characterized by deep causal chains and multi-entity modifications. This work points toward a future where graph-guided causal reasoning amplifies the capabilities of LLM-based autonomous software agents, impacting both theory and practice in AI-driven software engineering.