Product Requirements Document (PRD)

# Product Requirements Document (PRD)
## Promo Scenario Co-Pilot

**Version**: 1.0  
**Date**: 2024-10-20  
**Status**: In Development

---

## 1. Executive Summary

### 1.1 Product Vision

Promo Scenario Co-Pilot is an AI-powered system that transforms promotional campaign planning from an ad-hoc, spreadsheet-driven process into a data-driven, intelligent workflow. It enables promotional leads to quickly identify opportunities, model multiple scenarios, optimize for business impact, and generate creative assets—all within a unified interface.

### 1.2 Problem Statement

**Current State**:
- Promotional leads manually test only a few scenarios due to time constraints
- External factors (weather, events) are underutilized
- Impact on sales, margin, and EBIT is uncertain
- Creative asset generation is time-consuming and inconsistent
- No systematic learning from past campaigns

**Pain Points**:
1. **Speed**: Takes days to manually model scenarios
2. **Quality**: Limited scenario exploration leads to suboptimal decisions
3. **Consistency**: Ad-hoc spreadsheets lack standardization
4. **Context**: External factors not systematically considered
5. **Execution**: Creative briefs created from scratch each time

### 1.3 Solution Overview

An AI-powered co-pilot that:
1. **Discovers** opportunities through automated data analysis
2. **Models** multiple scenarios with automated KPI calculation
3. **Optimizes** scenarios for maximum business impact
4. **Generates** creative briefs and asset specifications
5. **Learns** from post-campaign performance to improve accuracy

---

## 2. Target Users

### 2.1 Primary User: Promotional Lead

**Profile**:
- Role: Marketing/Promotions Manager
- Experience: 3-10 years in retail/promotions
- Technical Level: Intermediate (comfortable with data, not coding)
- Goals: Close gaps vs targets, maximize promotional ROI

**Needs**:
- Quick scenario modeling
- Data-backed recommendations
- Clear KPI visualization
- Creative asset support

### 2.2 Secondary Users

- **Marketing Director**: Strategic oversight, approval
- **Finance Manager**: Margin and EBIT validation
- **Creative Team**: Asset generation support

---

## 3. User Stories

### 3.1 Discovery

**As a** promotional lead  
**I want to** see my current gap vs target and identified opportunities  
**So that** I can quickly understand what needs to be addressed

**Acceptance Criteria**:
- Display gap vs target chart for selected month
- Show identified opportunities with estimated potential
- Include contextual factors (weather, events)
- Allow filtering by department/channel

### 3.2 Scenario Modeling

**As a** promotional lead  
**I want to** create and compare multiple promotional scenarios  
**So that** I can choose the best approach

**Acceptance Criteria**:
- Create scenario from brief or manual input
- Compare 2-3 scenarios side-by-side
- See KPIs (sales, margin, EBIT, units) for each
- View breakdown by channel, department, segment
- Get validation feedback

### 3.3 Optimization

**As a** promotional lead  
**I want to** find optimal scenarios that balance sales and margin  
**So that** I can maximize business impact

**Acceptance Criteria**:
- Generate optimized scenarios based on objectives
- See efficient frontier (trade-offs)
- Rank scenarios by business impact
- Get recommendations with rationale

### 3.4 Creative Generation

**As a** promotional lead  
**I want to** generate creative briefs and asset copy from scenarios  
**So that** I can quickly brief the creative team

**Acceptance Criteria**:
- Generate structured creative brief
- Create copy for key assets (homepage hero, banners, in-store)
- Adapt messaging for different segments
- Export brief and assets

### 3.5 Data Processing

**As a** system administrator  
**I want to** process XLSB files and load them into the database  
**So that** the system has up-to-date data for analysis

**Acceptance Criteria**:
- Upload/process multiple XLSB files
- Merge files by date ranges
- Clean and validate data
- Generate data quality report
- Store in database for other agents

---

## 4. Functional Requirements

### 4.1 Data Processing Module

**FR-1.1**: System must process XLSB files (Web and Stores data)

**FR-1.2**: System must clean and standardize data formats:
- Dates in ISO format (YYYY-MM-DD)
- Channels: "online" or "offline"
- Departments: standardized list
- Numeric values: non-negative, proper types

**FR-1.3**: System must merge multiple files handling:
- Date range overlaps
- Duplicate records
- Missing values

**FR-1.4**: System must validate data quality:
- Completeness checks
- Accuracy validation
- Consistency checks
- Timeliness verification

**FR-1.5**: System must store processed data in database:
- Daily aggregation by channel and department
- Promo flag identification
- Indexing for fast queries

### 4.2 Discovery Module

**FR-2.1**: System must calculate baseline forecasts:
- Day-of-week patterns
- Seasonal adjustments
- Trend analysis

**FR-2.2**: System must identify gaps vs targets:
- Sales value gap
- Margin percentage gap
- Units gap

**FR-2.3**: System must gather contextual data:
- Weather forecasts
- Events and holidays
- Seasonality factors

**FR-2.4**: System must generate opportunities:
- Identify high-potential departments
- Estimate promotional potential
- Rank by priority

### 4.3 Scenario Lab Module

**FR-3.1**: System must create scenarios from:
- Natural language briefs
- Manual parameter input
- Template-based generation

**FR-3.2**: System must calculate scenario KPIs:
- Total sales, margin, EBIT, units
- Breakdown by channel
- Breakdown by department
- Breakdown by segment

**FR-3.3**: System must compare scenarios:
- Side-by-side KPI comparison
- Visual charts
- Trade-off analysis

**FR-3.4**: System must validate scenarios:
- Discount limits
- Margin thresholds
- KPI plausibility
- Brand compliance

### 4.4 Optimization Module

**FR-4.1**: System must generate optimized scenarios:
- Based on objectives (maximize sales/margin/EBIT)
- Respecting constraints
- Multiple candidate scenarios

**FR-4.2**: System must calculate efficient frontier:
- Trade-offs between objectives
- Pareto-optimal solutions
- Visualization

**FR-4.3**: System must rank scenarios:
- By weighted objective function
- With recommendations
- Including rationale

### 4.5 Creative Module

**FR-5.1**: System must generate creative briefs:
- Objectives and messaging
- Target audience
- Tone and style
- Mandatory elements

**FR-5.2**: System must generate asset copy:
- Homepage hero
- Category banners
- In-store sheets
- Email headers

**FR-5.3**: System must adapt messaging:
- By customer segment
- By channel (online/offline)
- By department focus

### 4.6 Post-Mortem Module

**FR-6.1**: System must analyze actual vs forecast:
- Calculate error percentages
- Identify root causes
- Generate insights

**FR-6.2**: System must detect effects:
- Post-promo dip
- Cannibalization
- Halo effects

**FR-6.3**: System must update models:
- Adjust uplift coefficients
- Improve forecast accuracy
- Learn from patterns

### 4.7 Chat Co-Pilot

**FR-7.1**: System must provide conversational interface:
- Answer "why" questions
- Explain calculations
- Provide what-if analysis

**FR-7.2**: System must be context-aware:
- Know current screen
- Understand active scenarios
- Access relevant data

---

## 5. Non-Functional Requirements

### 5.1 Performance

**NFR-1.1**: Scenario creation: < 5 seconds  
**NFR-1.2**: KPI calculation: < 3 seconds  
**NFR-1.3**: Data processing: < 5 minutes for 1M records  
**NFR-1.4**: Page load: < 2 seconds  
**NFR-1.5**: API response time (p95): < 1 second

### 5.2 Scalability

**NFR-2.1**: Support 100 concurrent users  
**NFR-2.2**: Handle 10M+ sales records  
**NFR-2.3**: Process 10+ XLSB files simultaneously

### 5.3 Reliability

**NFR-3.1**: System uptime: 99.5%  
**NFR-3.2**: Data processing success rate: > 99%  
**NFR-3.3**: Error recovery: automatic retry for transient failures

### 5.4 Security

**NFR-4.1**: Authentication required for all endpoints  
**NFR-4.2**: API keys with expiration  
**NFR-4.3**: Data encryption at rest and in transit  
**NFR-4.4**: Audit trail for all decisions

### 5.5 Usability

**NFR-5.1**: Intuitive UI requiring minimal training  
**NFR-5.2**: Responsive design (desktop and tablet)  
**NFR-5.3**: Accessibility: WCAG 2.1 AA compliance  
**NFR-5.4**: Help documentation available in-app

### 5.6 Observability

**NFR-6.1**: All LLM calls traced via Phoenix  
**NFR-6.2**: Performance metrics tracked  
**NFR-6.3**: Error logging and alerting

---

## 6. Technical Constraints

### 6.1 Technology Stack

- **Backend**: Python 3.10+, LangChain, FastAPI
- **Frontend**: React 18+, TypeScript, Tailwind CSS
- **Database**: PostgreSQL (production), DuckDB (local)
- **Observability**: Phoenix Arize
- **UI Components**: ReactBits.dev

### 6.2 Data Sources

- XLSB files (Web and Stores sales data)
- Weather API: Open-Meteo (free, no API key required)
- CDP (mock for hackathon, real API for production)
- Targets and configuration (internal)

### 6.3 Integration Requirements

- Must integrate with existing data warehouse
- Must support export to Excel/CSV
- Must support webhook notifications

---

## 7. Success Metrics

### 7.1 User Adoption

- **Target**: 80% of promotional leads use system within 3 months
- **Measure**: Monthly active users (MAU)

### 7.2 Time Savings

- **Target**: 70% reduction in scenario modeling time
- **Measure**: Average time to create scenario (before: 4 hours, after: 1 hour)

### 7.3 Decision Quality

- **Target**: 20% improvement in promotional ROI
- **Measure**: Actual vs forecast accuracy, margin impact

### 7.4 User Satisfaction

- **Target**: NPS > 50
- **Measure**: Quarterly user surveys

---

## 8. MVP Scope

### 8.1 Included

- Data processing (XLSB → database)
- Baseline forecast calculation
- Scenario creation and comparison (3 scenarios)
- KPI calculation and validation
- Creative brief generation
- Chat co-pilot (basic)
- Discovery screen
- Scenario Lab screen

### 8.2 Excluded (Future)

- Advanced ML models for uplift
- Real-time optimization
- Image generation for creatives
- Multi-tenant support
- Advanced post-mortem analytics
- Mobile app

---

## 9. User Flows

### 9.1 Primary Flow: Create and Compare Scenarios

1. User opens Discovery screen
2. System shows gap vs target for October
3. User describes problem in chat: "We're -3M vs target, need promo 22-27 Oct for TVs & Gaming"
4. System generates 3 scenarios (Conservative, Balanced, Aggressive)
5. User views comparison table with KPIs
6. User selects "Balanced" scenario
7. User adjusts parameters (max discount = 20%)
8. System recalculates KPIs
9. User clicks "Generate Creative Pack"
10. System generates brief and asset copy
11. User exports and shares with creative team

### 9.2 Data Processing Flow

1. Admin uploads XLSB files
2. System queues processing job
3. Data Analyst Agent processes files:
   - Reads XLSB files
   - Cleans and standardizes
   - Merges by date ranges
   - Validates quality
4. System stores in database
5. System generates quality report
6. Other agents can now access data

---

## 10. Risk Assessment

### 10.1 Technical Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|------------|------------|
| LLM API rate limits | High | Medium | Cache responses, use cheaper models |
| Data quality issues | High | Medium | Robust validation, error handling |
| Performance with large datasets | Medium | Low | Optimize queries, use indexes |
| Integration complexity | Medium | Medium | Phased integration, fallbacks |

### 10.2 Business Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|------------|------------|
| Low user adoption | High | Low | Training, support, clear value prop |
| Forecast inaccuracy | High | Medium | Continuous learning, model updates |
| Data privacy concerns | Medium | Low | Compliance, encryption, access control |

---

## 11. Timeline

### Phase 1: MVP (Hackathon - 14 hours)
- Core data processing
- Basic scenario modeling
- Simple UI screens
- Chat co-pilot

### Phase 2: Beta (4 weeks)
- Full feature set
- Production data integration
- User testing and feedback
- Performance optimization

### Phase 3: Production (8 weeks)
- Production deployment
- User training
- Monitoring and support
- Iterative improvements

---

## 12. Dependencies

### 12.1 External

- LLM API access (OpenAI/Anthropic)
- Weather API
- CDP API (for production)
- Data warehouse access

### 12.2 Internal

- Historical sales data (XLSB files)
- Targets and configuration
- Brand guidelines
- User access management

---

## 13. Open Questions

1. Should we support multi-currency?
2. How to handle regional variations?
3. Integration with existing promo planning tools?
4. Real-time data updates or batch processing?
5. Approval workflow for scenarios?

---

## 14. Appendix

### 14.1 Glossary

- **Baseline**: Forecast without promotions
- **Uplift**: Increase in sales due to promotion
- **Scenario**: A specific promotional campaign configuration
- **KPI**: Key Performance Indicator (sales, margin, EBIT, units)
- **Post-Mortem**: Analysis after campaign completion

### 14.2 References

- Architecture Documentation
- API Specification
- Database Schema
- System Prompts

---

**Document Owner**: Product Team  
**Last Updated**: 2024-10-20  
**Next Review**: 2024-11-20