invest-copilot/tasks/fix-alert-test-and-complete-sector-rotation/SPEC.md

Task: Fix Alert Test & Complete Sector Rotation Service

Current State

The invest-copilot project is at Phase 1-6 complete, with Phase 2 (Data Pipeline) and Phase 5 (Sector Rotation) marked as "In Progress".

Critical Issues Found

1. Failing Test: tests/test_alerts.py::TestAlertCRUD::test_get_all_alerts

   • Creates 2 alerts successfully (201)
   • GET request returns total: 0 instead of total: 2
   • Root cause: watchlist fixture not properly linked to test user's watchlists

2. Incomplete Sector Rotation Service (services/rotation_service.py)

   • Hardcoded ETF list (XLK, XLF, XLE, etc.)
   • No proper ranking algorithm (rank_now, rank_previous, rank_change missing)
   • Missing rotation_signal field (bullish/bearish/neutral)
   • No macro context or analysis summary
   • Uses random data in some calculations
   • Only stores 30 days of prices instead of full history

Project Structure

• Backend: FastAPI, asyncpg, Pydantic v2, Celery + Redis
• Database: PostgreSQL + TimescaleDB (hypertables for time-series)
• Frontend: Next.js 16, React 19, TypeScript, Zustand, TanStack Query
• Testing: pytest with 192 tests (1 currently failing)

Recommended Next Task

Phase 1: Fix Alert Test (Quick Win)

Goal: Make all 192 tests pass

Steps:

1. Investigate conftest.py watchlist fixture
2. Ensure watchlist is created with proper user_id ownership
3. Verify alert creation links to user's watchlist
4. Run full test suite to confirm all pass

Acceptance Criteria:

• pytest tests/ returns 0 failures
• All 192 tests pass

Phase 2: Complete Sector Rotation Service

Goal: Implement a production-ready sector rotation detection system

Current Gaps:

• No ranking algorithm (needs rank_now, rank_previous, rank_change)
• Missing rotation_signal (bullish/bearish/neutral based on momentum)
• No macro context (S&P 500 benchmark comparison)
• No analysis summary generation
• Hardcoded ETF list (should be configurable)
• Uses only 30 days of data (should use full history for ranking)

Implementation Plan:

1. Add missing fields to rotation_service.py:

   • rank_now: Current rank among all sectors
   • rank_previous: Previous period rank
   • rank_change: Difference (positive = improving)
   • rotation_signal: bullish/bearish/neutral based on momentum thresholds
   • macro_context: S&P 500 vs sector comparison
   • analysis_summary: Human-readable summary

2. Implement ranking algorithm:

   • Sort sectors by relative_strength
   • Assign ranks
   • Compare with previous day's ranks (from database)
   • Calculate rank_change

3. Add rotation signal logic:

   • bullish: momentum_20d > 0.05 AND rank_change > 0
   • bearish: momentum_20d < -0.05 AND rank_change < 0
   • neutral: everything else

4. Add macro context:

   • Fetch SPY prices
   • Compare sector momentum vs SPY momentum
   • Store in macro_context field

5. Make ETF list configurable:

   • Read from database or config
   • Allow dynamic sector ETF mapping

6. Add tests:

   • Test ranking algorithm
   • Test rotation signal logic
   • Test macro context calculation
   • Test edge cases (missing data, single sector)

Acceptance Criteria:

• All rotation fields populated correctly
• Ranking algorithm produces consistent results
• Rotation signals match expected thresholds
• Tests cover all new logic
• Service can be called via Celery task for scheduled runs

Why This Task First?

1. Fixes a critical blocker: The failing test indicates a data ownership bug that could affect other features
2. Completes a core feature: Sector rotation is a key differentiator for this investment tool
3. Both are high-value: The test fix is quick (1-2 hours), the rotation service is substantial but well-scoped
4. Aligns with project phases: Directly addresses the "In Progress" items in the README

Files to Modify

• src/backend/tests/conftest.py - Fix watchlist fixture
• src/backend/services/rotation_service.py - Complete rotation logic
• src/backend/routers/sectors.py - Update if needed
• src/backend/tasks/rotation_tasks.py - Add Celery task for scheduled runs
• src/backend/tests/test_rotation.py - Add new tests

Estimated Effort

• Fix alert test: 1-2 hours
• Complete sector rotation: 4-6 hours
• Total: 5-8 hours

Risks & Mitigations

• Risk: Watchlist fixture issue may affect other tests
  • Mitigation: Run full test suite after fix, check all watchlist-related tests
• Risk: Sector rotation logic may be complex
  • Mitigation: Start with simple ranking, add macro context in second pass
• Risk: Database schema may need updates for new fields
  • Mitigation: Check init.sql, add migration if needed

Next Steps After This Task

1. Complete data pipeline (Phase 2)
2. Implement PWA features (Phase 7)
3. Add integration tests
4. Performance optimization