# Track Specification: On-Demand Definition Lookup (on_demand_def_lookup_20260306)

## Overview
Add ability for agent to request specific class/function definitions during discussion. Parse @symbol syntax to trigger lookup and display inline in the discussion.

## Current State Audit

### Already Implemented (DO NOT re-implement)

#### MCP Tool (mcp_client.py)
- **`py_get_definition(path, name)`**: Returns full source of class/function/method
- **Already exposed to AI** as tool #18 in tool inventory
- **Parameters**: `path` (file path), `name` (symbol name, supports `ClassName.method_name`)

#### Code Outline Tool (outline_tool.py)
- **`CodeOutliner` class**: Uses AST to extract code structure
- **`outline(code: str) -> str`**: Returns hierarchical outline

#### GUI Discussion (gui_2.py)
- **`_render_discussion_panel()`**: Renders discussion history
- **`_send_callback()`**: Handles user input submission
- **No @symbol parsing exists**

### Gaps to Fill (This Track's Scope)
- No parsing of @symbol syntax in user input
- No automatic definition lookup on @symbol
- No inline display of definitions in discussion
- No click-to-navigate to source file

## Architectural Constraints

### Lookup Performance
- Definition lookup MUST complete in <100ms
- Use existing MCP tool - no new parsing needed

### Display Integration
- Definitions displayed inline in discussion flow
- Preserve discussion context (don't replace user message)

## Architecture Reference

### Key Integration Points

| File | Lines | Purpose |
|------|-------|---------|
| `src/gui_2.py` | ~1400-1500 | `_send_callback()` - add @symbol parsing |
| `src/gui_2.py` | ~1200-1300 | `_render_discussion_panel()` - display definitions |
| `src/mcp_client.py` | ~400-450 | `py_get_definition()` - existing tool |
| `src/outline_tool.py` | 10-30 | `CodeOutliner` class |

### Proposed Flow
```
1. User types: "Check @MyClass.method_name implementation"
2. _send_callback() parses input, finds @symbol
3. Call py_get_definition() for symbol
4. Inject definition into discussion as system message
5. Display with syntax highlighting
6. Click on definition opens file at line
```

## Functional Requirements

### FR1: @Symbol Parsing
- Parse user input for `@SymbolName` pattern
- Support: `@FunctionName`, `@ClassName`, `@ClassName.method_name`
- Extract symbol name and optional file context

### FR2: Definition Retrieval
- Use existing `py_get_definition()` MCP tool
- If no file specified, search all project files
- Handle "symbol not found" gracefully

### FR3: Inline Display
- Inject definition as special discussion entry
- Use monospace font with syntax highlighting
- Show file path and line numbers
- Collapse long definitions (>50 lines)

### FR4: Click Navigation
- Store file path and line number with definition
- On click, open file viewer at that location
- Use existing file viewing mechanism

## Non-Functional Requirements

| Requirement | Constraint |
|-------------|------------|
| Lookup Time | <100ms per symbol |
| Display Impact | No frame drop during display |
| Memory | Definitions not cached (lookup each time) |

## Testing Requirements

### Unit Tests
- Test @symbol regex parsing
- Test symbol name extraction
- Test file path resolution

### Integration Tests (via `live_gui` fixture)
- Type @symbol, verify definition appears
- Click definition, verify navigation works

## Out of Scope
- Auto-fetch on unknown symbols (explicit @ only)
- Definition editing inline
- Multi-file symbol search optimization

## Acceptance Criteria
- [ ] @symbol triggers lookup
- [ ] Definition displays inline in discussion
- [ ] File path and line numbers shown
- [ ] Click navigates to source
- [ ] "Not found" handled gracefully
- [ ] Uses existing `py_get_definition()`
- [ ] 1-space indentation maintained
