# Known Issues & Limitations
### 1. Hallucinated File Paths
The LLM frequently assumes standard file structures that do not exist in the specific repository (e.g., guessing `python/core/layer_management.py` in QGIS). While `PathValidator` attempts to fuzzy-match or auto-correct these paths, it often leads to wasted search iterations or reading irrelevant files when the guess is too far off.
### 2. Polyglot Confusion
In repositories containing multiple languages (e.g., CodeQL having Java, Python, and QL files), the planner often struggles to target the correct "layer" of the application. For example, when asked about JavaScript function definitions in CodeQL, it grepped the target JavaScript files rather than the QL extraction logic, resulting in 0% recall.
### 3. Grep "Blindness" via Truncation
The `grep` tool truncates results (default 50 matches). If a search term is too common (e.g., `save` in Django or `mesh` in Infinigen), the actual relevant code definition may be cut from the output, leading the LLM to believe the code isn't there or to focus on irrelevant usage examples instead of definitions.
### 4. Keyword Mismatch (Semantic Gap)
The current "Keyword Hunt" strategy fails when the implementation uses different terminology than the user's question.
* **Example:** In `claude_flow_messaging`, the user asked about "sending messages". The tool searched for "message" and "communication", but missed the actual implementation if it used terms like "EventBus", "Dispatch", or "Signal" without explicitly naming them in the initial "Technical Terms" step.
### 5. Circular Search Loops
When initial strong keywords fail, the agent tends to retry similar variations of the same `grep` pattern or repeatedly lists the same directory, burning through the iteration limit without exploring alternative directories (observed in `infinigen_mesh_primitives`).
