ok

conductor/tracks/on_demand_def_lookup_20260306/spec.md

@@ -1,33 +1,115 @@
 # 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.
+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
-- **`mcp_client.py_get_definition()`**: Returns full definition source
-- **`outline_tool.py`**: Code outlining
+### Already Implemented (DO NOT re-implement)
 
-### Gaps to Fill
-- No @symbol parsing in discussion input
-- No inline definition display
-- No click-to-source navigation
+#### 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
-- Parse `@ClassName` or `@function_name` in input
-- Display definition inline in discussion
-- Click to jump to source file
-- Uses existing `py_get_definition()` tool
 
-## Key Integration Points
-| File | Purpose |
-|-----|---------|
-| `src/gui_2.py` | Input parsing, definition display |
-| `src/mcp_client.py` | `py_get_definition()` |
+### 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
-- [ ] Click navigation functional
-- [ ] 1-space indentation
+- [ ] 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