adaptive-pricing/docs/ImplementationRoadmap.md

Adaptive Pricing Implementation Roadmap

Status: draft, implementation-facing.

Purpose

This roadmap translates the strategic goals in INTENT.md into an executable implementation sequence for the current repository state.

The root research roadmap in research/PricingResearchRoadmap.md remains the conceptual and research-first planning artifact. This document starts from the current implementation reality: a Coulomb-specific economic observatory MVP under projects/coulomb-pricing/observatory/.

Current Baseline

The repository already provides:

• ledger-backed economics and liquidity tracking
• cost-floor, value-range, and market-context views
• file-based Stripe / Bubble / OpenRouter imports
• scenario comparison for a small set of candidate pricing models
• rules-based pricing recommendations
• a local dashboard API and UI

The repository does not yet provide:

• a canonical, generic pricing-model schema
• a validation engine for pricing constraints and commitments
• comparable customer LTV estimation
• a customer-tuning solver
• outbound payment-provider execution
• governance workflows for publishing and changing pricing

Sequencing Principles

• Preserve the observatory MVP as a proving ground while extracting generic core logic.
• Build schema and validation before solver or provider execution.
• Keep the internal pricing model as the source of truth; execution adapters come later.
• Require explainability at each stage: validation, simulation, tuning, and publish.
• Convert repository planning into milestone workplans rather than one large umbrella plan.

Milestones

Milestone	Goal	Primary workplan	Dependencies	Exit signal
M0	Economic observatory baseline	ADAPTIVE-WP-0002	done	Coulomb ledger, dashboard, simulator, recommendations
M1	Extract canonical pricing core and schema	ADAPTIVE-WP-0003	M0	Generic schema and validator adopted by Coulomb data
M2	Add boundary engine and explainable validation	ADAPTIVE-WP-0004	M1	Pricing configurations are validated against explicit constraints
M3	Upgrade economics to comparable-customer LTV and richer simulation	ADAPTIVE-WP-0005	M1, M2	Simulations compare models using segment/risk-aware economics
M4	Implement customer-tuning solver prototype	ADAPTIVE-WP-0006	M2, M3	Tuned configurations can be proposed, evaluated, and explained
M5	Add provider abstraction and Stripe publication flow	ADAPTIVE-WP-0007	M1, M2, M3	Internal pricing definitions can publish Stripe artifacts safely
M6	Add governance and recommendation workflows	ADAPTIVE-WP-0008	M4, M5	Pricing changes become auditable, explainable, and operational

Milestone Details

M1 — Canonical Pricing Core And Schema

Create a reusable pricing core that can represent more than the current subscription-only observatory model. Expand beyond the current narrow PricingModel structure to include charge components, commitments, tunable parameters, eligibility, and provider-mapping metadata.

M2 — Boundary Engine And Explainable Validation

Turn strategic boundary conditions into testable rules. A pricing configuration must be accepted or rejected by explicit logic, not only by dashboard review. This milestone defines hard and soft constraints, invalid-configuration reasons, and commitment-backed discount semantics.

M3 — Comparable Customer LTV And Richer Simulation

Extend the current period snapshot and fixed-assumption simulator into an engine that can compare pricing configurations across customer segments, usage forecasts, risk classes, and contract conditions. This is the economics core needed by any seller-safe adaptive system.

M4 — Customer-Tuning Solver Prototype

Expose a customer/seller configuration interface where selected parameters are tunable and the solver adjusts the rest while preserving seller economics. This milestone is the first actual realization of the adaptive-pricing thesis in INTENT.md.

M5 — Provider Abstraction And Stripe Publication

Add an outbound execution layer that maps internal pricing definitions to Stripe artifacts. This is where the repo moves from observatory-only to operational pricing infrastructure.

M6 — Governance And Recommendation Workflows

Operationalize the engine with approval policies, publish/change workflows, auditable recommendations, experiment guardrails, and customer-facing safe tuning contracts.

Workplan Set

• ADAPTIVE-WP-0003 — Canonical pricing core and schema extraction
• ADAPTIVE-WP-0004 — Boundary engine and explainable validation
• ADAPTIVE-WP-0005 — Comparable customer LTV and simulation upgrade
• ADAPTIVE-WP-0006 — Customer-tuning solver prototype
• ADAPTIVE-WP-0007 — Provider abstraction and Stripe publication
• ADAPTIVE-WP-0008 — Governance and recommendation workflows

Near-Term Recommendation

Start with ADAPTIVE-WP-0003.

The current implementation bottleneck is not UI or provider execution. It is the absence of a sufficiently expressive internal pricing model. Until that schema exists, later milestones would hard-code MVP assumptions into layers that should remain generic.