# MixLift Execution Framework

**CEO Directive | March 7, 2026 | Derived from OPERATING_PLAN.md**

This document assigns workstreams to manager agents, defines communication protocols, maps dependencies, and separates agent-implementable work from founder-only tasks. Each manager should use this as their operating instructions.

---

## 1. WORKSTREAM ASSIGNMENTS

### 1.1 Engineering Manager

**Mandate:** Harden, don't build. Zero new modeling features. Monitoring, fail-closed licensing, and integration tests are your priorities.

**Repos:**
- MCP package + modeling engine: `/Users/felix/software-projects/mixlift/`
- License API: `/Users/felix/software-projects/mixlift-api/`

| ID | Deliverable | Due | What to Implement | Key Files |
|---|---|---|---|---|
| B2 | Structured logging on License API | Mar 10 | Add JSON structured logging with `request_id`, masked `license_key`, `tier`, `latency` fields to the License API. Replace `logging.basicConfig` with `python-json-logger` or manual JSON formatter. Add request_id middleware. | `mixlift-api/src/mixlift_api/main.py` |
| B3 | `last_validated_at` timestamp in licenses table | Mar 10 | Add `last_validated_at` column to the `licenses` table schema in `database.py`. Update `validate_license` endpoint in `main.py` to SET this timestamp on every successful validation call. Add a migration or ALTER TABLE in `init_db()`. | `mixlift-api/src/mixlift_api/database.py`, `mixlift-api/src/mixlift_api/main.py` |
| B4 | Verify Render disk persistence for SQLite | Mar 11 | Write a test or verification script that confirms SQLite DB survives Render redeploy. Document findings in `docs/render-persistence.md`. If persistence fails, document the mitigation path (S3 backup or Render Postgres). | `mixlift-api/` |
| B5 | Rate limiting on license validation endpoint | Mar 12 | The License API already has `slowapi` rate limiting at 30/minute on `/v1/license/validate`. Operating plan says 60/minute per IP. **Decision: update the existing limit from 30 to 60 requests/minute** in `main.py:146`. Verify via test. | `mixlift-api/src/mixlift_api/main.py` (line 145) |
| B6 | End-to-end integration test in CI | Mar 14 | Create a single integration test that exercises: CSV load, format detect, tier enforcement, modeling pipeline (mocked MCMC), result formatting, memory save/load. Tests exist at `tests/test_integration/test_e2e.py` and `test_flow_gaps.py` -- review, fix any failures, and ensure they run in the CI workflow at `.github/workflows/ci.yml`. | `tests/test_integration/`, `.github/workflows/ci.yml` |
| B7 | Fail-closed license validation with 24hr cached grace period | Mar 18 | Currently `src/mixlift_mcp/license.py` falls back to free tier on ANY error (line 61-62). Implement: (1) on successful validation, cache the result with timestamp to a local file, (2) on API failure, check cache -- if <24hrs old, honor cached tier, (3) if cache is stale or absent, block paid features (return free tier). Never silently downgrade on API error for paid users. | `src/mixlift_mcp/license.py` |
| B9 | Update STRATEGY.md and PROJECT_STATUS.md | Mar 19 | Mark all shipped items as SHIPPED. Update architecture diagram. Remove "BLOCKED" from items that are live. Refer to Appendix C in OPERATING_PLAN.md for the ground truth of what is shipped. | `STRATEGY.md`, `PROJECT_STATUS.md` |
| B10 | LOO-CV implementation via ArviZ | Mar 25 | Integrate `az.loo()` into the model fit summary in `engine.py`. ArviZ is already a dependency. Add ELPD score + human-readable interpretation ("good fit" / "fair fit" / "poor fit" based on p_loo and warnings). Surface in MCP results via `server.py`. | `mixlift/modeling/engine.py`, `src/mixlift_mcp/server.py` |
| B11 | Strip raw saturation curves from MCP output | Mar 26 | A comment at `server.py:547` indicates this is ALREADY DONE -- curves are stripped, only traffic lights remain. **Verify** this is working correctly by checking the output dict. If curves still leak through, remove them. Write a test to assert no raw curve arrays in MCP output. | `src/mixlift_mcp/server.py` |
| B14 | Intercept decomposition (baseline/organic revenue) | Apr 2 | Surface the model intercept as "organic/baseline revenue" in the results dict. The PyMC-Marketing MMM model has an intercept -- extract it, annualize it, and present it as "estimated organic revenue (without any ad spend)." | `mixlift/modeling/engine.py`, `src/mixlift_mcp/server.py` |

**NOT in scope for Engineering Manager:**
- B1 (UptimeRobot) -- founder-only, external service signup
- B8 (Fix demo bugs) -- reactive, triggered by founder demos
- B12 (Fix onboarding bugs) -- reactive, triggered by customer onboarding
- B13 (Data hardening from real CSVs) -- reactive, triggered by real customer data

---

### 1.2 Data Science Manager

**Mandate:** Validate existing model quality. No new modeling features. LOO-CV is your flagship deliverable. Everything else is documentation and validation.

| ID | Deliverable | Due | What to Implement | Key Files |
|---|---|---|---|---|
| B10 | LOO-CV implementation (co-own with EM) | Mar 25 | Design the LOO-CV integration. Determine ELPD thresholds for "good/fair/poor" interpretation. Write the `compute_loo_cv()` function and its interpretation logic. Coordinate with EM on where it plugs into `engine.py`. ArviZ `az.loo()` is the implementation path. Document expected ELPD ranges for typical MMM models. | `mixlift/modeling/engine.py` |
| B14 | Intercept decomposition design (co-own with EM) | Apr 2 | Define how to extract baseline revenue from the model intercept. Specify the math: intercept * n_weeks for annualized baseline. Define how to present this alongside channel contributions. | `mixlift/modeling/engine.py` |
| NEW-DS1 | Model quality documentation | Mar 18 | Write `docs/model-quality.md` documenting: (a) what the default priors are and why, (b) convergence diagnostics (R-hat thresholds), (c) posterior predictive checks already shipped, (d) known limitations (short data, cross-channel interactions, point-estimate optimizer). This supports Sales demos and Marketing content. | `docs/model-quality.md` |
| NEW-DS2 | Sample dataset validation | Mar 14 | Validate the 8-channel sample dataset (created by Product Manager) to ensure it produces reasonable model outputs. Run the engine on it, verify convergence, check ROAS ranges are realistic for DTC eCommerce. File issues if outputs look unrealistic. | `data/sample_8channel.csv` (once PM creates it) |

---

### 1.3 Product Manager

**Mandate:** Sample dataset + guided first-run experience is your #1 priority. It is sales infrastructure, not a feature.

| ID | Deliverable | Due | What to Implement | Key Files |
|---|---|---|---|---|
| A4 | Create sample dataset (8-channel, 52-week CSV) | Mar 12 | Create a realistic synthetic CSV with 8 channels: google_search, meta_prospecting, meta_retargeting, tiktok, youtube, email, affiliate, direct_mail. 52 weekly rows. Spend ranges realistic for a $5M-$50M DTC brand ($30K-$80K/mo total ad spend). Include seasonality (Q4 bump). Revenue column with realistic correlation to spend. Save to `data/sample_8channel.csv`. | `data/sample_8channel.csv` (new) |
| A4 | Create first-run guide | Mar 12 | Write a 1-page guide at `docs/first-run-guide.md`: what the sample dataset represents, what to expect when you run it, how to interpret results (ROAS, saturation, budget optimizer). Target audience: marketing director with no data science background. Include the exact MCP prompt to use. | `docs/first-run-guide.md` (new) |
| A12 | Create "Day 0 case study" from sample data | Mar 17 | Run MixLift on the sample dataset, capture the output, and write up an anonymized case study at `docs/case-study-day0.md`. Show: dollar headline, saturation insights, budget reallocation recommendation. Format it for the landing page. | `docs/case-study-day0.md` (new) |
| B9 | Update STRATEGY.md and PROJECT_STATUS.md (co-own with EM) | Mar 19 | Review these docs from a product perspective. Ensure the feature status table is accurate. Remove references to features as "planned" when they are shipped. | `STRATEGY.md`, `PROJECT_STATUS.md` |

---

### 1.4 Marketing Manager

**Mandate:** Create content that drives inbound interest and supports outbound. All content must be implementable as files in the repo -- no external platform posting (that is founder-only).

| ID | Deliverable | Due | What to Implement | Key Files |
|---|---|---|---|---|
| A8 | LinkedIn carousel content (draft) | Mar 17 | Write the copy for "5 Signs Your Ad Budget Has a Leak" at `docs/content/linkedin-carousel-budget-leak.md`. 5 slides with headline + body + visual description. Founder will post. | `docs/content/linkedin-carousel-budget-leak.md` (new) |
| A9 | Reddit teardown post (draft) | Mar 19 | Write the post content for r/PPC or r/dtc at `docs/content/reddit-teardown.md`. Run analysis on anonymized sample data, write up results with commentary. Include CTA for comments (not post body). Founder will post. | `docs/content/reddit-teardown.md` (new) |
| A11 | MCP marketplace listing (draft) | Mar 18 | Write the marketplace description, install command, feature list, and screenshot descriptions at `docs/content/mcp-marketplace-listing.md`. Founder will submit. | `docs/content/mcp-marketplace-listing.md` (new) |
| NEW-MK1 | Improve outreach templates based on ICP | Mar 12 | Review existing `docs/outreach-templates.md` and `docs/icp-profiles.md`. Create 3 additional personalized template variants targeting specific ICP segments (DTC beauty, DTC food/bev, DTC apparel). Add to `docs/outreach-templates.md`. | `docs/outreach-templates.md` (existing) |
| NEW-MK2 | SEO-optimized README | Mar 14 | Update `README.md` with better positioning copy, clear install instructions, a "Quick Start" section referencing the sample dataset, and social proof placeholders. Target keywords: "marketing mix modeling", "Bayesian MMM", "media mix model", "MCP marketing". | `README.md` (existing) |
| NEW-MK3 | Landing page copy refresh | Mar 17 | Write updated landing page copy at `docs/content/landing-page-v2.md` incorporating the sample dataset, case study, and LOO-CV messaging. Founder will deploy to Netlify. | `docs/content/landing-page-v2.md` (new) |

---

### 1.5 Sales Lead

**Mandate:** Build the sales playbook and demo structure as docs. Actual outreach and demos are founder-only.

| ID | Deliverable | Due | What to Implement | Key Files |
|---|---|---|---|---|
| NEW-SL1 | 30-minute demo script | Mar 10 | Write a detailed demo script at `docs/sales/demo-script.md`. Cover: opening (2 min), problem framing (3 min), live analysis on sample data (10 min), results walkthrough (10 min), pricing + close (5 min). Include objection handling for common concerns (accuracy, data privacy, "why not Google Analytics"). | `docs/sales/demo-script.md` (new) |
| NEW-SL2 | Objection handling guide | Mar 12 | Expand the battle card at `docs/battle-card.md` with detailed responses to: "How is this better than platform attribution?", "We already have a BI tool", "Can I trust Bayesian models?", "What if I only have 6 months of data?", "Why $299/mo when I can hire a freelancer?". | `docs/battle-card.md` (existing) |
| NEW-SL3 | CRM tracking template | Mar 10 | Create `docs/sales/pipeline-tracker.md` -- a markdown table template for tracking: prospect name, company, outreach date, response, demo date, demo outcome, objections, close date, notes. Founder fills this in. | `docs/sales/pipeline-tracker.md` (new) |
| NEW-SL4 | Qualification scorecard | Mar 12 | Create `docs/sales/qualification-scorecard.md` based on Appendix B of the operating plan. Weighted scoring: revenue range (20%), ad spend (25%), channel count (15%), seniority (20%), pain signal (20%). Include "auto-disqualify" criteria. | `docs/sales/qualification-scorecard.md` (new) |
| NEW-SL5 | Pricing one-pager | Mar 14 | Create `docs/sales/pricing-one-pager.md`: what $299/mo includes, what free tier includes, comparison table, FAQ. This is a leave-behind for prospects after demos. | `docs/sales/pricing-one-pager.md` (new) |

---

### 1.6 Customer Success Manager

**Mandate:** Build the onboarding and retention playbooks as implementable docs. Actual customer interactions are founder-only.

| ID | Deliverable | Due | What to Implement | Key Files |
|---|---|---|---|---|
| A16 | Onboarding playbook (detailed) | Mar 14 | Expand Appendix A of the operating plan into `docs/cs/onboarding-playbook.md`. For each touchpoint (Day 0, 1, 3, 7, 14, 21, 30), include: email/message templates, call agendas, success criteria, escalation paths. | `docs/cs/onboarding-playbook.md` (new) |
| NEW-CS1 | MCP setup guide for customers | Mar 12 | Write `docs/cs/mcp-setup-guide.md`: step-by-step instructions for installing MixLift, configuring the MCP client (Claude Desktop, Cursor, etc.), setting the license key, and running first analysis. Include troubleshooting for common issues (Python version, pip errors, MCP connection). | `docs/cs/mcp-setup-guide.md` (new) |
| NEW-CS2 | Results interpretation guide | Mar 17 | Write `docs/cs/interpreting-results.md`: what each output section means (ROAS, confidence intervals, saturation traffic lights, budget optimizer, scenario mode). Include a "what to do next" section for each finding type. Target audience: marketing director. | `docs/cs/interpreting-results.md` (new) |
| NEW-CS3 | Retention health check template | Mar 21 | Create `docs/cs/retention-health-check.md`: a checklist the founder runs at Day 14 and Day 21 for each customer. Are they running analyses independently? Are they using scenario mode? Have they refreshed data? Triggers for intervention. | `docs/cs/retention-health-check.md` (new) |
| NEW-CS4 | Churn risk signals doc | Mar 21 | Create `docs/cs/churn-risk-signals.md`: early warning signs (no analysis after Day 7, no scenario mode usage, support tickets about accuracy, questions about cancellation). Action plan for each signal. | `docs/cs/churn-risk-signals.md` (new) |

---

## 2. COMMUNICATION PROTOCOL

### Status File

All managers write status to: `/Users/felix/software-projects/mixlift/docs/agent-status.md`

### Update Format

Each manager owns their section. Use this exact format:

```markdown
## [Role Name]

**Last updated:** YYYY-MM-DD HH:MM

### Completed
- [ID] Description (file path)

### In Progress
- [ID] Description -- ETA, blockers if any

### Blocked
- [ID] Description -- what is blocking, who can unblock

### Needs Review
- [ID] Description -- who should review, file path
```

### Update Cadence

- Update your section EVERY TIME you complete a deliverable or encounter a blocker.
- Before starting work, READ the full status file to check for cross-team updates.

### Escalation Path

- If blocked by another manager's output: note it in your "Blocked" section AND in the blocking manager's "Needs Review" section.
- If blocked by a founder-only item: note it in your "Blocked" section. The founder checks this file daily.

---

## 3. DEPENDENCY MAP

```
LEGEND: A --> B means "A must complete before B can start"
        A ~~> B means "A improves B but doesn't block it"

Week 1 (Mar 8-14):
  B2 (structured logging)          -- independent, no deps
  B3 (last_validated_at)           -- independent, no deps
  B5 (rate limiting update)        -- independent, no deps
  A4/PM (sample dataset)           -- independent, no deps
  A4/PM (first-run guide)          --> depends on sample dataset
  NEW-SL1 (demo script)            ~~> improved by sample dataset
  NEW-CS1 (MCP setup guide)        -- independent
  NEW-MK1 (outreach template ICP)  -- independent

Week 2 (Mar 15-21):
  B6 (integration test in CI)      ~~> improved by B2, B3 but not blocked
  B7 (fail-closed licensing)       -- independent, no deps
  B9 (update stale docs)           -- independent
  A12/PM (Day 0 case study)        --> DEPENDS ON: A4/PM sample dataset
  NEW-DS1 (model quality doc)      -- independent
  NEW-DS2 (sample data validation) --> DEPENDS ON: A4/PM sample dataset
  A8/MK (LinkedIn carousel)        ~~> improved by A12 case study
  NEW-MK3 (landing page copy)      --> DEPENDS ON: A12/PM case study
  NEW-CS2 (results interp guide)   -- independent

Week 3 (Mar 22-28):
  B10 (LOO-CV)                     -- independent (ArviZ already a dep)
  B11 (verify saturation strip)    -- independent
  NEW-CS3 (retention health check) -- independent
  NEW-CS4 (churn risk signals)     -- independent

Week 4 (Mar 29 - Apr 4):
  B14 (intercept decomposition)    -- independent
```

### Critical Path

The single most important dependency chain is:

```
A4/PM (sample dataset, Mar 12)
  --> NEW-DS2 (DS validates it, Mar 14)
  --> A12/PM (case study from it, Mar 17)
  --> NEW-MK3 (landing page copy, Mar 17)
```

If the sample dataset slips, the case study, landing page, and marketing content all slip. **PM: this is your #1 priority.**

### B10 (LOO-CV) Dependencies

B10 does NOT depend on B6 (integration tests). LOO-CV is a pure modeling addition using `az.loo()` on the InferenceData object that `engine.py` already produces. The integration test may need updating AFTER B10 ships, but B10 does not wait for it.

---

## 4. CROSS-TEAM HANDOFFS

| # | Producer | Consumer | Artifact | Handoff Point |
|---|---|---|---|---|
| H1 | Product Manager | Data Science Manager | `data/sample_8channel.csv` | PM creates by Mar 12. DS validates model output by Mar 14. If DS finds issues (non-convergence, unrealistic ROAS), PM revises the data. |
| H2 | Product Manager | Marketing Manager | `docs/case-study-day0.md` | PM creates by Mar 17. Marketing uses it as source material for landing page copy and LinkedIn content. |
| H3 | Product Manager | Sales Lead | `data/sample_8channel.csv` + `docs/first-run-guide.md` | Sales Lead references the sample dataset and guide in the demo script. Demo script should include the exact command to run the sample. |
| H4 | Data Science Manager | Engineering Manager | LOO-CV function design | DS defines the function signature, thresholds, and interpretation strings. EM implements the integration into `engine.py` and `server.py`. |
| H5 | Data Science Manager | Marketing Manager | `docs/model-quality.md` | Marketing uses model quality documentation to create credibility-building content (LinkedIn posts, landing page "How it works" section). |
| H6 | Sales Lead | Marketing Manager | `docs/sales/demo-script.md` | Marketing aligns content messaging with the demo narrative. The "hook" in outreach should match the demo opening. |
| H7 | Sales Lead | Customer Success Manager | `docs/sales/demo-script.md` + `docs/sales/qualification-scorecard.md` | CS onboarding playbook should reference what was promised during the sale. Qualification criteria inform onboarding intensity. |
| H8 | Customer Success Manager | Product Manager | `docs/cs/interpreting-results.md` | PM reviews interpretation guide for accuracy. Guide language should match MCP output labels exactly. |
| H9 | Engineering Manager | Customer Success Manager | B7 (fail-closed licensing) | CS setup guide must document what happens when the License API is down (cached grace period). Update `docs/cs/mcp-setup-guide.md` after B7 ships. |
| H10 | Engineering Manager | Sales Lead | B10 (LOO-CV) | Once LOO-CV ships, Sales Lead updates demo script to include "model validation" as a demo step. |

---

## 5. FOUNDER-ONLY ITEMS

These items require external service access, human judgment, or real-world interactions that agents cannot perform. The founder should review this list daily.

### Week 1 (Mar 8-14)

| ID | Item | Due | Notes |
|---|---|---|---|
| A1 | Record 90-second Loom demo video | Mar 9 | Shows CSV drop, model run, dollar headline, scenario mode. Requires Loom account. |
| A2 | Build LinkedIn prospect list (50 qualified DTC brands) | Mar 9 | Requires LinkedIn Sales Navigator or manual research. |
| A3 | Send first 25 LinkedIn DMs | Mar 10 | Use templates from `docs/outreach-templates.md`. Personalize per prospect. |
| A5 | Send next 25 LinkedIn DMs | Mar 14 | Adjust messaging based on Week 1 response rates. |
| A6 | Complete 2+ live demos | Mar 14 | On prospect's own data or sample data. |
| B1 | UptimeRobot monitoring setup | Mar 9 | External service. Ping `/health` every 5 min. Alert to phone. |
| B4 | Verify Render disk persistence | Mar 11 | Requires Render dashboard access. Agent can write the verification script, but founder must run the redeploy test. |

### Week 2 (Mar 15-21)

| ID | Item | Due | Notes |
|---|---|---|---|
| A7 | Send 50 more LinkedIn DMs (total: 100) | Mar 21 | 10-15/day cadence. |
| A8 | Post LinkedIn carousel | Mar 17 | Marketing Manager drafts content; founder posts. |
| A9 | Post Reddit teardown | Mar 19 | Marketing Manager drafts content; founder posts. |
| A10 | Complete 5+ total live demos | Mar 21 | Track outcomes in pipeline tracker. |
| A11 | Submit MCP marketplace listing | Mar 18 | Marketing Manager drafts content; founder submits. |
| A12 | Publish case study on landing page | Mar 17 | PM writes content; founder deploys to Netlify. |
| B8 | Fix demo-killing bugs (if any) | Rolling | Same-day turnaround. Agents can help fix once reported. |

### Week 3 (Mar 22-28)

| ID | Item | Due | Notes |
|---|---|---|---|
| A13 | Send 50 more DMs (total: 150) | Mar 28 | |
| A14 | Complete 10+ total live demos | Mar 28 | |
| A15 | Close first paying customer | Mar 28 | $299 via Stripe. |
| A16 | Begin onboarding (use CS playbook) | On close | CS Manager writes the playbook; founder executes it. |

### Week 4 (Mar 29 - Apr 4)

| ID | Item | Due | Notes |
|---|---|---|---|
| A17 | Send 50 more DMs (total: 200) | Apr 4 | |
| A18 | Complete 15+ total live demos | Apr 4 | |
| A19 | Close 3 paying customers | Apr 4 | |
| A20 | First customer Day 7 interpretation call | Per playbook | |
| B12 | Fix customer onboarding bugs | Rolling | Agents can help fix once reported. |
| B13 | Data hardening from real CSVs | Rolling | Agents can help fix once reported. |

### Ongoing Founder Tasks

- **Weekly dashboard update** (every Monday starting Mar 17): Fill in metrics from Section 5 of the operating plan.
- **Pipeline tracker maintenance**: Update `docs/sales/pipeline-tracker.md` after every outreach batch and demo.
- **Agent status review**: Check `docs/agent-status.md` daily for blockers requiring founder action.

---

## 6. MANAGER LAUNCH ORDER

Managers should be launched in this order to respect dependencies:

1. **Engineering Manager** and **Sales Lead** -- can start immediately, no dependencies
2. **Product Manager** -- can start immediately (sample dataset has no deps)
3. **Customer Success Manager** -- can start immediately (setup guide has no deps)
4. **Marketing Manager** -- can start on outreach templates immediately; content work benefits from PM's sample dataset (Mar 12)
5. **Data Science Manager** -- can start model quality doc immediately; sample validation waits for PM (Mar 12)

In practice, all six can launch in parallel. The dependency map above shows where handoffs occur.

---

## 7. GROUND RULES FOR ALL MANAGERS

1. **Read the operating plan first.** It is at `/Users/felix/software-projects/mixlift/OPERATING_PLAN.md`. Understand the five operating principles before making any decision.

2. **Do not build new features.** The EM's "harden, don't build" directive applies to everyone. If you think something requires a new capability, propose it in your status update -- do not implement it.

3. **Use absolute file paths.** All file references must be absolute paths from `/Users/felix/software-projects/mixlift/`.

4. **Update agent-status.md after every deliverable.** This is how the team communicates.

5. **Check for blockers before starting.** Read the full `docs/agent-status.md` before beginning work.

6. **Code changes require tests.** Any code change to `mixlift/` or `src/mixlift_mcp/` must include or update relevant tests in `tests/`.

7. **Do not modify `.env` files.** Environment variables are founder-managed.

8. **Do not push to remote.** All changes stay local. The founder reviews and pushes.

---

*This framework was produced on March 7, 2026, by the CEO agent.*
*Source of truth: `/Users/felix/software-projects/mixlift/OPERATING_PLAN.md`*
*Status tracking: `/Users/felix/software-projects/mixlift/docs/agent-status.md`*
