# Agencio Predict - Build Phases & Roadmap

## Philosophy

**Start narrow, prove the loop, then expand.**

The biggest risk isn't building the wrong features — it's building too many at once
and never proving any of them work. Each phase has a clear "done" signal.

---

## Phase 0: Foundation (Week 1)

**Goal:** Database + basic API scaffold. Nothing visible to users yet.

### Tasks:
- [ ] Set up Supabase tables (core schema from 03-database-schema.md)
  - prediction_categories (with seed data)
  - prediction_events
  - prediction_signals
  - prediction_snapshots
  - prediction_explanations
- [ ] Set up RLS policies
- [ ] Create API route scaffold in Next.js
  - `GET /api/predict/v1/events`
  - `GET /api/predict/v1/events/:id`
  - `POST /api/predict/v1/events`
  - `GET /api/predict/v1/events/:id/timeline`
- [ ] Seed 10-15 manually curated prediction events
- [ ] Set up TypeScript types for all entities

### Done signal:
API returns seeded events. Database is queryable.

---

## Phase 1: Signal Engine + Terminal MVP (Weeks 2-3)

**Goal:** Live data flowing in, displayed in a basic terminal UI.

### Backend:
- [ ] Polymarket data ingestion (scrape or API)
  - Scheduled job every 15 minutes
  - Map to prediction_signals table
  - Auto-create snapshots
- [ ] NewsAPI integration
  - RSS feed polling
  - Keyword matching to events
- [ ] Basic probability aggregation
  - Weighted average of signals
  - Confidence scoring (based on signal count + diversity)
- [ ] Divergence detection
  - Compare market price vs sentiment
  - Flag HIGH/EXTREME divergence

### Frontend:
- [ ] `/predict` page layout
- [ ] EventFilters component (category, probability range, search)
- [ ] PredictionCard component
- [ ] EventGrid (responsive grid of cards)
- [ ] MiniSparkline (inline probability chart)
- [ ] Click-through to EventDetail (basic)

### Done signal:
User visits `/predict`, sees 10+ events with live probabilities updating.
Can filter by category and search.

---

## Phase 2: Explanations + Event Detail (Weeks 3-4)

**Goal:** "Why did it move?" — the core differentiator.

### Backend:
- [ ] Explanation generation pipeline
  - Trigger on >5% probability shift in <4 hours
  - Collect relevant signals
  - Claude API call to generate explanation
  - Store in prediction_explanations
- [ ] Explanation API endpoints
  - `GET /events/:id/explanations`
  - `POST /events/:id/explain` (manual trigger)

### Frontend:
- [ ] EventDetail page (`/predict/event/:slug`)
  - EventHeader (probability, confidence, countdown)
  - TrendChart (probability over time with Recharts)
  - Volume overlay
- [ ] WhyItMoved panel
  - ExplanationCard component
  - FactorList component
  - ExplanationTimeline
- [ ] SignalFeed (raw signal list with source icons)
- [ ] Supabase Realtime subscription for live updates

### Done signal:
Click any event, see probability chart + AI-generated explanations.
When probability shifts, new explanation appears in real-time.

---

## Phase 3: Trust Layer v1 (Weeks 4-5)

**Goal:** Trust scoring and manipulation detection.

### Backend:
- [ ] Trust scoring service
  - Volume consistency scoring (detect spikes)
  - Temporal analysis (timing anomalies)
  - Source diversity scoring
  - Sentiment authenticity (bot detection basics)
- [ ] Trust tables creation
  - prediction_trust_scores
  - prediction_trust_flags
- [ ] Trust API endpoints
  - `GET /trust/:eventId`
  - `GET /trust/:eventId/flags`
- [ ] Flag generation
  - INSIDER_TIMING detection (bet → news gap analysis)
  - VOLUME_SPIKE detection (statistical outlier)
  - BOT_SENTIMENT detection (account age, pattern matching)

### Frontend:
- [ ] TrustBadge on PredictionCard
- [ ] TrustPanel on EventDetail
  - TrustScoreGauge
  - TrustBreakdown (radar chart)
  - FlagList
- [ ] `/predict/trust` dashboard (basic)
  - FlaggedEvents list
  - Global trust overview

### Done signal:
Events show trust scores. Manipulation flags appear when detected.
Users can view trust breakdown per event.

---

## Phase 3.5: Triggers & Actions Engine (Weeks 5-6)

**Goal:** Automated rules that fire external actions when prediction conditions are met.

### Backend:
- [ ] Create `prediction_rules` table
- [ ] Create `prediction_rule_executions` table
- [ ] Create `prediction_action_connections` table
- [ ] Add `previous_*` columns to `prediction_events`
- [ ] Trigger evaluation engine (runs on every signal ingest / snapshot)
- [ ] Action executor with retry logic (max 3x, exponential backoff)
- [ ] Core triggers: `prob_crosses_above/below`, `prob_shift`, `trust_flag_raised`, `event_resolved`
- [ ] Core actions: `webhook`, `notify_slack`, `notify_email`, `notify_in_app`
- [ ] Template variable interpolation (`{{ event.title }}`, etc.)
- [ ] Cooldown / rate limiting / active hours enforcement
- [ ] Rules CRUD API
- [ ] Connections API + OAuth flow (Slack first)
- [ ] System-level pre-built rules (explanation on big move, trust recompute on spike)
- [ ] Dry-run / test mode

### Frontend:
- [ ] `/predict/rules` page
- [ ] Rule builder (trigger selector + action builder + settings)
- [ ] Execution log with per-action status
- [ ] Connected platforms panel (connect/disconnect/test)
- [ ] System rules override UI (enable/disable defaults)

### Done signal:
User creates a rule "When probability crosses 70%, notify Slack."
Rule fires when condition is met. Execution log shows success/failure.

---

## Phase 4: Marketing Prediction Engine (Weeks 6-8)

**Goal:** Campaign prediction — the unique wedge.

### Backend:
- [ ] Marketing prediction service
  - Campaign scoring algorithm
  - Variant comparison engine
  - Claude API integration for behavioural analysis
  - Persona Engine integration (Agencio link)
- [ ] Marketing tables
  - prediction_campaigns
  - prediction_campaign_variants
- [ ] Marketing API endpoints
  - `POST /marketing/predict/campaign`
  - `POST /marketing/predict/viral`
  - `GET /marketing/campaigns/:id`

### Frontend:
- [ ] `/predict/campaigns` page
- [ ] CampaignForm
  - Campaign details input
  - AudienceSelector (persona link)
  - PlatformPicker
  - VariantBuilder (add A/B/C variants)
- [ ] PredictionResults
  - VariantComparison (side-by-side cards)
  - ScoringFactorsRadar (per variant)
  - RecommendedBadge
  - ExplanationPanel

### Done signal:
User enters campaign details + 2 variants, gets scored prediction with
explanation of why one variant is recommended over the other.

---

## Phase 5: Calibration Engine (Weeks 7-8)

**Goal:** Track prediction accuracy. Build credibility.

### Backend:
- [ ] Resolution system
  - prediction_resolutions table
  - Resolution UI for marking outcomes
  - Dispute window mechanism
- [ ] Calibration computation
  - Brier score calculation
  - Accuracy-at-threshold metrics
  - Calibration curve generation
  - Rolling window computation (7D, 30D, 90D, ALL)
- [ ] Calibration API
  - `GET /calibration/report`
- [ ] Campaign outcome recording
  - `POST /marketing/campaigns/:id/outcome`
  - Feed back into prediction model accuracy

### Frontend:
- [ ] CalibrationBanner on main terminal (rolling score)
- [ ] `/predict/calibration` page
  - OverallScore display
  - CalibrationChart (predicted vs actual scatter)
  - AccuracyByCategory
  - BrierScoreTrend (over time)
  - RecentResolutions list

### Done signal:
After 20+ resolved events, calibration page shows meaningful accuracy data.
Users can see "we predicted X, and Y% of the time we were right."

---

## Phase 6: Polish + Social Sentiment (Weeks 8-10)

**Goal:** Deeper social data. Production readiness.

### Backend:
- [ ] X/Twitter API integration (sentiment analysis)
- [ ] Reddit API integration (subreddit sentiment)
- [ ] Improved sentiment scoring (NLP / Claude-based)
- [ ] Social signal weighting
- [ ] Alert/notification system (email, webhook)

### Frontend:
- [ ] Social sentiment overlay on TrendChart
- [ ] Sentiment source breakdown
- [ ] Notification preferences
- [ ] Mobile-responsive refinement
- [ ] Performance optimization (virtualised lists, chart performance)
- [ ] Onboarding flow for new users

### Done signal:
Social sentiment flows into predictions. Terminal feels production-ready.

---

## Phase 7: API Product + Monetisation (Weeks 10-12)

**Goal:** Revenue. Ship the API product.

### Backend:
- [ ] API key management
- [ ] Rate limiting by tier
- [ ] Usage tracking / metering
- [ ] Webhook delivery system
- [ ] API documentation (auto-generated from OpenAPI spec)

### Frontend:
- [ ] API key management UI
- [ ] Usage dashboard
- [ ] Billing integration (Stripe)
- [ ] Pricing page
- [ ] API docs page

### Done signal:
External users can sign up, get an API key, and query prediction data.
Usage is metered and billable.

---

## Milestones Summary

| Phase | What | Duration | Done Signal |
|-------|------|----------|-------------|
| 0 | Foundation | 1 week | API returns seeded data |
| 1 | Signal Engine + Terminal | 2 weeks | Live events with probabilities |
| 2 | Explanations | 1 week | AI explains movements |
| 3 | Trust Layer | 1 week | Manipulation detection live |
| 4 | Marketing Engine | 2 weeks | Campaign prediction works |
| 5 | Calibration | 1 week | Accuracy tracking live |
| 6 | Social + Polish | 2 weeks | Production-ready |
| 7 | API + Revenue | 2 weeks | Paying customers possible |

**Total: ~12 weeks to full product**
**MVP (Phases 0-2): ~4 weeks**

---

## Risk Mitigation

| Risk | Mitigation |
|------|-----------|
| Polymarket API changes/blocks | Build scraper fallback, abstract data source layer |
| AI explanation quality is poor | Start with templates + Claude, iterate on prompts |
| Trust scoring too many false positives | Start with HIGH threshold, tune with data |
| Marketing predictions inaccurate | Be transparent about calibration, improve with feedback loop |
| Low initial data volume | Seed aggressively, cover popular categories |
| Regulatory concerns | Position as intelligence/analytics, not betting. Legal review Phase 6 |