CodeScout: Contextual Problem Statement Enhancement for Software Agents

TL;DR

This work introduces CodeScout, a contextual query refinement approach that systematically converts underspecified user requests into comprehensive, actionable problem statements through lightweight pre-exploration of the target codebase through structured analysis before task execution.

Abstract

Current AI-powered code assistance tools often struggle with poorly-defined problem statements that lack sufficient task context and requirements specification. Recent analysis of software engineering agents reveals that failures on such underspecified requests are highly correlated with longer trajectories involving either over-exploration or repeated attempts at applying the same fix without proper evolution or testing, leading to suboptimal outcomes across software development tasks. We introduce CodeScout, a contextual query refinement approach that systematically converts underspecified user requests into comprehensive, actionable problem statements through lightweight pre-exploration of the target codebase. Our key innovation is demonstrating that structured analysis before task execution can supplement existing agentic capabilities without requiring any modifications to their underlying scaffolds. CodeScout performs targeted context scoping, conducts multi-perspective analysis examining potential fixes and exploration opportunities, then synthesizes these insights into enhanced problem statements with reproduction steps, expected behaviors, and targeted exploration hints. This pre-exploration directly addresses the identified failure patterns by reducing non-converging agent trajectories while clarifying user intent in natural language space. We evaluate CodeScout using state-of-the-art agentic scaffolds and language models on SWEBench-Verified, demonstrating a 20\% improvement in resolution rates with up to 27 additional issues resolved compared to the default baseline method. Our results suggest that systematic query refinement through contextual analysis represents a promising direction for enhancing AI code assistance capabilities.

Figures (28)

• Figure 1: The original SWEBench problem statement for Instance django__django-11790 lack relevant initial context. As a result, the downstream agent is not able to fix the issue, despite spending 21 steps exploring the repository, analyzing code, iterating the fix patch. In contrast, the enhanced problem statement generated by our approach resolves the issue in 6 agentic steps, as it includes relevant insights that can be used off-the-bat by the agent.
• Figure 2: CodeScout: The pre-exploration with Repository Knowledge Graph Construction, which represents code structure and relationships. Building on this, three main stages follow: 1) High Level Scoping, where an LLM agent identifies relevant exploration targets, 2) Fine-grained Context Analysis, which extracts structured insights for each target, and 3) Problem Synthesis, where the original problem statement is combined with filtered insights to generate the augmented specification.
• Figure 3: Localization comparison (file-level and function-level) using SWE-Agent as the scaffold.
• Figure 4: Cumulative issues resolved as a function of total tokens consumed (input+output). (a) Agent-only token accounting; (b) token accounting including augmentation overhead.
• Figure 5: Augmentation metrics: number of LLM calls, tokens and dollar cost per instance.