WHITEBOARD.md

WHITEBOARD.md - Agent Communication Hub

This file is the central source of truth for agent coordination. Update this file when starting work, completing tasks, or encountering blockers.

---

Project Status Overview

MVP Target: CLI application that outputs NBA player prop projections with edge scores

Current Priority: P0 - Core functionality (game fetching, odds retrieval, projection models)

---

Agent Status

Agent	Status	Current Task	Last Update
Data Engineer	🔴 Not Started	Initialize /data/ modules	-
Quantitative Modeler	🔴 Not Started	Implement statistical distributions	-
Logic Architect	🔴 Not Started	Build adjustment algorithms	-
Test Engineer	🔴 Not Started	Write test scaffolds	-
Integration Specialist	🔴 Not Started	Create main.py entry point	-

Status Legend

• 🔴 Not Started
• 🟡 In Progress
• 🟢 Complete
• 🔵 Blocked

---

Issues & Blockers

ID	Agent	Issue	Severity	Resolution	Status
-	-	No issues reported	-	-	-

Severity Levels

• Critical: Blocks other agents, cannot proceed
• High: Significantly impacts timeline
• Medium: Workaround available
• Low: Minor inconvenience

---

Dependencies Queue

Task	Blocked By	Needed From	Status
Model projections	SQLite schema	Data Engineer	⏳ Waiting
Logic adjustments	Distribution functions	Quantitative Modeler	⏳ Waiting
CLI output	Edge score calculation	Logic Architect	⏳ Waiting
Test fixtures	All modules	All agents	⏳ Waiting

---

Priority Notes

P0 Items (Required for MVP)

1. ✍️ Data Engineer must create database schema and populate with team/player data
2. ✍️ Data Engineer must implement nba_client.py for game fetching
3. ✍️ Data Engineer must implement odds_client.py for prop lines
4. ✍️ Quantitative Modeler must implement 4 stat projection functions (points, rebounds, assists, threes)
5. ✍️ Integration Specialist must create CLI entry point

P1 Items (Core+ Features)

1. ⬚ Logic Architect must build pace adjustment module
2. ⬚ Logic Architect must build defensive efficiency loader
3. ⬚ Logic Architect must implement usage reallocation
4. ⬚ Logic Architect must calculate ensemble edge scores

P2 Items (Nice-to-Have)

1. ⬚ Integration Specialist adds garbage time filtering
2. ⬚ Test Engineer adds property-based tests with hypothesis

---

Beginner Guidelines

Naming Conventions

Files & Modules

• Use snake_case for all Python files: nba_client.py, usage_realloc.py
• Use __init__.py to make directories importable packages
• Test files mirror source: tests/test_models.py tests models/

Functions & Variables

# ✅ Good
def calculate_edge_score(model_projection, market_line):
    edge = model_projection - market_line
    return edge

projected_points = 25.3
pace_factor = 1.02

# ❌ Avoid
def calc(proj, line):  # Too abbreviated
    return proj - line

projPts = 25.3  # Mixed case

Classes

# ✅ Good
class ProjectionEngine:
    def __init__(self, config):
        self.config = config

# ❌ Avoid
class projection_engine:  # Wrong case
    pass

Constants

# ✅ Good (at top of file or in config.py)
DEFAULT_PACE_FACTOR = 1.0
MIN_EDGE_THRESHOLD = 0.5
MAX_GAMES_SAMPLE = 15

# ❌ Avoid
default_pace_factor = 1.0  # Should be UPPER_CASE if constant

SQL Tables

• Always plural: players, games, projections, results
• Foreign keys reference singular ID: player_id, game_id

---

Feature Development Rules

API Integration (Data Engineer)

1. Never log API keys - Use config.py to load from .env
2. Always wrap in try/except - Handle network failures gracefully
3. Respect rate limits - Add delays between calls; check quota headers
4. Return structured data - Use dictionaries or dataclasses, not raw JSON strings

# ✅ Good
def get_todays_games():
    try:
        board = scoreboard.ScoreBoard()
        return board.get_dict()
    except Exception as e:
        logger.error(f"Failed to fetch games: {e}")
        return {}

# ❌ Avoid
def get_games():
    return scoreboard.ScoreBoard()  # No error handling

Statistical Modeling (Quantitative Modeler)

1. Document math - Every function must explain formula in docstring
2. Return variance - Point estimates aren't enough; always return confidence bounds
3. Validate distributions - Test mean/variance properties with known parameters
4. Handle edge cases - What if player has 0 attempts? What if sample is empty?

# ✅ Good
def conway_maxwell_poisson_pmf(k, lambda_param, nu_param):
    """
    Conway-Maxwell-Poisson PMF for under-dispersed data.
    Used for rebounds/assists where variance < mean.
    
    Formula: P(X=k) = (λ^k / (k!)^ν) / Z(λ, ν)
    
    Args:
        k: Count value
        lambda_param: Rate parameter (λ)
        nu_param: Dispersion parameter (ν)
    
    Returns:
        Probability mass for value k
    """
    if lambda_param < 0 or nu_param < 0:
        raise ValueError("Parameters must be non-negative")
    # ... implementation

Logic & Adjustments (Logic Architect)

1. Explain adjustments - Document why pace factor is 1.02, not 1.5
2. Keep weights configurable - Put thresholds in config.py, not hardcoded
3. Log decisions - When usage is reallocated, log which players got what

# ✅ Good
def apply_pace_adjustment(base_projection, team_pace, league_avg_pace):
    """
    Adjust projection based on pace factor.
    
    Pace Factor = Team Pace / League Average Pace
    
    A team playing 105 possessions vs league avg 100 has pace_factor = 1.05
    Projection gets multiplied by this factor.
    """
    pace_factor = team_pace / league_avg_pace
    return base_projection * pace_factor

# ❌ Avoid
def adjust(proj, pace):
    return proj * pace * 1.02  # Magic numbers unexplained

Testing (Test Engineer)

1. Mock all external calls - No network access in tests
2. Use fixtures - Create reusable test data
3. Test edge cases - Not just happy path
4. Assert on math - Verify statistical properties

# ✅ Good
@pytest.fixture
def mock_nba_api():
    with patch('nba_api.stats.endpoints.scoreboard.ScoreBoard') as mock:
        mock.return_value.get_dict.return_value = {'games': []}
        yield mock

def test_empty_game_day(mock_nba_api):
    result = get_todays_games()
    assert result == {'games': []}

---

Git Workflow

Commit Message Format

[Agent] Scope: Brief description

- Detailed change 1
- Detailed change 2

Closes #IssueNumber

Example:

[Data Engineer] API: Add error handling to odds client

- Retry logic for 5xx errors
- Rate limit header logging
- Graceful degradation on quota exceeded

Closes #12

Branch Naming

• data-engineer/api-integration
• modeler/cmp-distribution
• logic/pace-adjustments
• test/unit-tests-models
• integration/cli-entry-point

---

Communication Log

Timestamp	Agent	Message
2026-03-27 10:00	System	WHITEBOARD.md initialized
-	-	-

---

Quick Reference

File Locations

/data/nba_client.py      # NBA API wrapper
/data/odds_client.py     # The Odds API wrapper
/data/storage.py         # SQLite operations
/models/distributions.py # Statistical PDFs/PMFs
/models/projections.py   # Projection builders
/logic/adjustments.py    # Pace & defensive adjustments
/logic/usage_realloc.py  # DNP usage redistribution
/logic/ensemble.py       # Edge score calculation
/utils/formatting.py     # CLI output tables
/utils/garbage_time.py   # Garbage time filter
/main.py                 # Entry point
/config.py               # Environment variables
/.env                    # API keys (gitignored)

Environment Variables

ODDS_API_KEY=your_key_here
DATABASE_PATH=./data/projections.db
EDGE_THRESHOLD=0.5
LOG_LEVEL=INFO

Test Commands

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=. tests/

# Run specific test
pytest tests/test_models.py::test_cmp_distribution -v

---

Definition of Done Checklist

Before marking any task complete:

• Code follows naming conventions in BLUEPRINT.md
• All functions have docstrings
• No hardcoded API keys or credentials
• Error handling for all external calls
• Unit tests pass locally
• Coverage >80% for modified files
• WHITEBOARD.md updated with completion status
• No blocker comments remaining

---

Last Updated: 2026-03-27 Next Review: When first agent completes P0 task