docs: add TDD fix plan for Magentic mode report generation

docs/bugs/FIX_PLAN_MAGENTIC_MODE.md

@@ -0,0 +1,227 @@
+# Fix Plan: Magentic Mode Report Generation
+
+**Related Bug**: `P0_MAGENTIC_MODE_BROKEN.md`
+**Approach**: Test-Driven Development (TDD)
+**Estimated Scope**: 4 tasks, ~2-3 hours
+
+---
+
+## Problem Summary
+
+Magentic mode runs but fails to produce readable reports due to:
+
+1. **Primary Bug**: `MagenticFinalResultEvent.message` returns `ChatMessage` object, not text
+2. **Secondary Bug**: Max rounds (3) reached before ReportAgent completes
+3. **Tertiary Issues**: Stale "bioRxiv" references in prompts
+
+---
+
+## Fix Order (TDD)
+
+### Phase 1: Write Failing Tests
+
+**Task 1.1**: Create test for ChatMessage text extraction
+
+```python
+# tests/unit/test_orchestrator_magentic.py
+
+def test_process_event_extracts_text_from_chat_message():
+    """Final result event should extract text from ChatMessage object."""
+    # Arrange: Mock ChatMessage with .content attribute
+    # Act: Call _process_event with MagenticFinalResultEvent
+    # Assert: Returned AgentEvent.message is a string, not object repr
+```
+
+**Task 1.2**: Create test for max rounds configuration
+
+```python
+def test_orchestrator_uses_configured_max_rounds():
+    """MagenticOrchestrator should use max_rounds from constructor."""
+    # Arrange: Create orchestrator with max_rounds=10
+    # Act: Build workflow
+    # Assert: Workflow has max_round_count=10
+```
+
+**Task 1.3**: Create test for bioRxiv reference removal
+
+```python
+def test_task_prompt_references_europe_pmc():
+    """Task prompt should reference Europe PMC, not bioRxiv."""
+    # Arrange: Create orchestrator
+    # Act: Check task string in run()
+    # Assert: Contains "Europe PMC", not "bioRxiv"
+```
+
+---
+
+### Phase 2: Fix ChatMessage Text Extraction
+
+**File**: `src/orchestrator_magentic.py`
+**Lines**: 192-199
+
+**Current Code**:
+```python
+elif isinstance(event, MagenticFinalResultEvent):
+    text = event.message.text if event.message else "No result"
+```
+
+**Fixed Code**:
+```python
+elif isinstance(event, MagenticFinalResultEvent):
+    if event.message:
+        # ChatMessage may have .content or .text depending on version
+        if hasattr(event.message, 'content') and event.message.content:
+            text = str(event.message.content)
+        elif hasattr(event.message, 'text') and event.message.text:
+            text = str(event.message.text)
+        else:
+            # Fallback: convert entire message to string
+            text = str(event.message)
+    else:
+        text = "No result generated"
+```
+
+**Why**: The `agent_framework.ChatMessage` object structure may vary. We need defensive extraction.
+
+---
+
+### Phase 3: Fix Max Rounds Configuration
+
+**File**: `src/orchestrator_magentic.py`
+**Lines**: 97-99
+
+**Current Code**:
+```python
+.with_standard_manager(
+    chat_client=manager_client,
+    max_round_count=self._max_rounds,  # Already uses config
+    max_stall_count=3,
+    max_reset_count=2,
+)
+```
+
+**Issue**: Default `max_rounds` in `__init__` is 10, but workflow may need more for complex queries.
+
+**Fix**: Verify the value flows through correctly. Add logging.
+
+```python
+logger.info(
+    "Building Magentic workflow",
+    max_rounds=self._max_rounds,
+    max_stall=3,
+    max_reset=2,
+)
+```
+
+**Also check**: `src/orchestrator_factory.py` passes config correctly:
+```python
+return MagenticOrchestrator(
+    max_rounds=config.max_iterations if config else 10,
+)
+```
+
+---
+
+### Phase 4: Fix Stale bioRxiv References
+
+**Files to update**:
+
+| File | Line | Change |
+|------|------|--------|
+| `src/orchestrator_magentic.py` | 131 | "bioRxiv" → "Europe PMC" |
+| `src/agents/magentic_agents.py` | 32-33 | "bioRxiv" → "Europe PMC" |
+| `src/app.py` | 202-203 | "bioRxiv" → "Europe PMC" |
+
+**Search command to verify**:
+```bash
+grep -rn "bioRxiv\|biorxiv" src/
+```
+
+---
+
+## Implementation Checklist
+
+```
+[ ] Phase 1: Write failing tests
+    [ ] 1.1 Test ChatMessage text extraction
+    [ ] 1.2 Test max rounds configuration
+    [ ] 1.3 Test Europe PMC references
+
+[ ] Phase 2: Fix ChatMessage extraction
+    [ ] Update _process_event() in orchestrator_magentic.py
+    [ ] Run test 1.1 - should pass
+
+[ ] Phase 3: Fix max rounds
+    [ ] Add logging to _build_workflow()
+    [ ] Verify factory passes config correctly
+    [ ] Run test 1.2 - should pass
+
+[ ] Phase 4: Fix bioRxiv references
+    [ ] Update orchestrator_magentic.py task prompt
+    [ ] Update magentic_agents.py descriptions
+    [ ] Update app.py UI text
+    [ ] Run test 1.3 - should pass
+    [ ] Run grep to verify no remaining refs
+
+[ ] Final Verification
+    [ ] make check passes
+    [ ] All tests pass (108+)
+    [ ] Manual test: run_magentic.py produces readable report
+```
+
+---
+
+## Test Commands
+
+```bash
+# Run specific test file
+uv run pytest tests/unit/test_orchestrator_magentic.py -v
+
+# Run all tests
+uv run pytest tests/unit/ -v
+
+# Full check
+make check
+
+# Manual integration test
+set -a && source .env && set +a
+uv run python examples/orchestrator_demo/run_magentic.py "metformin alzheimer"
+```
+
+---
+
+## Success Criteria
+
+1. `run_magentic.py` outputs a readable research report (not `<ChatMessage object>`)
+2. Report includes: Executive Summary, Key Findings, Drug Candidates, References
+3. No "Max round count reached" error with default settings
+4. No "bioRxiv" references anywhere in codebase
+5. All 108+ tests pass
+6. `make check` passes
+
+---
+
+## Files Modified
+
+```
+src/
+├── orchestrator_magentic.py   # ChatMessage fix, logging
+├── agents/magentic_agents.py  # bioRxiv → Europe PMC
+└── app.py                     # bioRxiv → Europe PMC
+
+tests/unit/
+└── test_orchestrator_magentic.py  # NEW: 3 tests
+```
+
+---
+
+## Notes for AI Agent
+
+When implementing this fix plan:
+
+1. **DO NOT** create mock data or fake responses
+2. **DO** write real tests that verify actual behavior
+3. **DO** run `make check` after each phase
+4. **DO** test with real OpenAI API key via `.env`
+5. **DO** preserve existing functionality - simple mode must still work
+6. **DO NOT** over-engineer - minimal changes to fix the specific bugs