diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a5aaf1b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,182 @@ +# adaptive-pricing — Agent Instructions + +## Repo Identity + +**Purpose:** Auto-regulating market value exploring price engine. + +**Domain:** helix_forge +**Repo slug:** adaptive-pricing +**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c` +**Workplan prefix:** `ADAPTIVE-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workstreams for this domain +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=adaptive-pricing&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=adaptive-pricing&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=adaptive-pricing + ``` + This syncs task status from files into the hub DB. + +--- + +{CREDENTIAL_ROUTING} + + + + +## Repository Layout + +| Path | Purpose | +|------|---------| +| `INTENT.md`, `docs/`, `research/`, `registry/` | Generic adaptive-pricing framework | +| `projects//` | Deployment-specific MVP material (integrations, configs, project docs) | +| `workplans/` | ADR-001 workplans and task tracking (including MVP execution plans) | + +Do not place project-specific MVP documentation in `specs/` or other generic +paths. The Coulomb Social MVP lives under `projects/coulomb-pricing/`; its +workplan remains `workplans/ADAPTIVE-WP-0002-economic-observatory-mvp.md`. + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/ADAPTIVE-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-ADAPTIVE-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: ADAPTIVE-WP-NNNN +type: workplan +title: "..." +domain: helix_forge +repo: adaptive-pricing +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: ADAPTIVE-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=adaptive-pricing` + (or send a message to the hub agent via `POST /messages/`) diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..95f2005 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,38 @@ +# SCOPE + +> This file was generated by `statehub register`. Refine it as the repository +> boundaries become clearer. + +## One-liner + +Auto-regulating market value exploring price engine. + +## Core Idea + +adaptive-pricing exists to provide the capability described in INTENT.md. + +## In Scope + +- Maintain the repository's primary implementation. +- Keep docs, tests, and operational metadata current. +- Generic framework documentation (`INTENT.md`, `docs/`, `research/`, `registry/`). +- Project-specific deployments under `projects//`. + +## Out of Scope + +- Own unrelated adjacent systems. +- Make irreversible operational decisions without human approval. +- Project-specific MVP material in `specs/` or other generic doc paths (use + `projects//` instead). + +## Current State + +- Status: active; implementation and stability should be verified by the repo agent. + +## Getting Oriented + +- Start with: INTENT.md +- Product requirements (generic): docs/ProductRequirementsDocument.md +- Agent instructions: AGENTS.md +- Workplans: workplans/ +- Coulomb MVP artifacts: projects/coulomb-pricing/ diff --git a/docs/ProductRequirementsDocument.md b/docs/ProductRequirementsDocument.md new file mode 100644 index 0000000..3a3d03a --- /dev/null +++ b/docs/ProductRequirementsDocument.md @@ -0,0 +1,1228 @@ +# ProductRequirementsDocument.md + +# Adaptive Pricing + +## Version + +0.1 + +## Status + +Draft + +## Repository + +`adaptive-pricing` + +--- + +# 1. Purpose + +Adaptive Pricing is a pricing intelligence and execution platform for discovering, validating, optimizing, and operating pricing strategies across the full lifecycle of products, services, communities, platforms, and marketplaces. + +The product supports pricing from the earliest inception of an idea through exploration, introduction, growth, maturity, saturation, and decline. + +Adaptive Pricing treats pricing not as a static billing configuration, but as a lifecycle-spanning learning and control capability. + +--- + +# 2. Product Thesis + +Pricing is one of the most important mechanisms for discovering product-market fit. + +A product team does not merely need to know: + +> What should we charge? + +It needs to understand: + +> What value are we creating, for whom, under which conditions, at what cost, against which alternatives, with which risks, and through which commercial model? + +Adaptive Pricing helps builders answer these questions systematically. + +The product shall provide a practical framework for: + +* forming pricing hypotheses +* understanding cost floors +* exploring value ranges +* analyzing market competition +* selecting pricing models +* designing pricing experiments +* simulating economic outcomes +* exposing safe pricing choices to customers +* optimizing seller economics +* translating pricing decisions into executable payment-provider configurations + +The long-term ambition is to become an **auto-regulating market value exploration pricing engine**. + +--- + +# 3. Problem Statement + +Pricing decisions are often made too late, too statically, and with too little evidence. + +Common problems include: + +* pricing is considered only after a product is already built +* cost structures are poorly understood +* willingness to pay is guessed rather than explored +* customer value is not connected to price +* competitive alternatives are not modeled explicitly +* pricing experiments are informal and hard to compare +* payment-provider configuration becomes hidden business logic +* discounts are granted without understanding LTV impact +* usage-based pricing is introduced without cost attribution +* dynamic pricing damages trust when it is not explainable +* pricing is not adapted to lifecycle stage +* customer preferences are not used as pricing intelligence + +Adaptive Pricing addresses these problems by making pricing hypotheses, models, observations, simulations, constraints, and executions explicit. + +--- + +# 4. Unique Value Proposition + +Adaptive Pricing supports pricing throughout the complete product lifecycle, beginning before the product exists. + +Unlike billing systems, payment providers, subscription managers, or revenue platforms, Adaptive Pricing is not primarily concerned with invoice execution. + +Its core value is to help teams discover and operate economically valid pricing models. + +Adaptive Pricing combines: + +1. **Pricing intelligence** + Understanding value, cost, competition, risk, customer behavior, and lifecycle stage. + +2. **Pricing model design** + Defining reusable, composable, testable pricing models. + +3. **Pricing experimentation** + Structuring and evaluating evidence about willingness to pay and value perception. + +4. **Pricing simulation** + Comparing pricing alternatives before activation. + +5. **Customer-tunable pricing** + Allowing customers to adjust pricing trade-offs while preserving seller economics. + +6. **Pricing execution** + Translating validated pricing models into payment-provider artifacts. + +7. **Pricing governance** + Keeping pricing decisions explainable, auditable, bounded, and lifecycle-aware. + +--- + +# 5. Core Concept + +The core object of Adaptive Pricing is not the price. + +The core object is the **Pricing Hypothesis**. + +A Pricing Hypothesis captures a belief about value, willingness to pay, cost, risk, customer behavior, competition, or pricing mechanics. + +Examples: + +* Customers will pay a monthly subscription for access to a community and its knowledge assets. +* Usage-based AI functionality should be priced based on actual provider cost plus a working margin. +* Customers prefer predictable monthly cost over low base price with volatile overage. +* Annual commitment justifies a lower unit price. +* Volume discounts are only economically valid when tied to minimum turnover commitments. +* Enterprise customers value support, compliance, and SLA more than raw usage volume. +* A product in exploration should optimize for learning, while a mature product should optimize for margin and retention. + +Adaptive Pricing helps validate, refine, reject, and operationalize such hypotheses. + +--- + +# 6. Lifecycle Model + +Adaptive Pricing shall support pricing work across the following lifecycle phases. + +## 6.1 Idea + +The product does not yet exist. + +Primary questions: + +* Who might receive value? +* What pain or desire is addressed? +* What alternatives already exist? +* How expensive is the problem? +* What pricing patterns might fit? +* Which willingness-to-pay assumptions should be tested? + +Supported capabilities: + +* value hypothesis capture +* customer segment assumptions +* alternative and competition mapping +* early pricing pattern suggestions +* research task generation +* initial value-range estimation + +--- + +## 6.2 Exploration + +The product concept, prototype, or early offer is being tested. + +Primary questions: + +* Will anyone pay? +* What will they pay for? +* Which value metric seems plausible? +* Which pricing model creates the least friction? +* What must be learned before scaling? + +Supported capabilities: + +* pricing experiments +* pilot pricing +* customer interview capture +* willingness-to-pay research +* cost floor estimation +* value metric exploration +* early pricing model comparison + +--- + +## 6.3 Introduction + +The product enters the market with first paying customers. + +Primary questions: + +* Which pricing model converts? +* Which customer segments respond? +* Which costs matter? +* Which pricing promises must be stable? +* What price communication works? + +Supported capabilities: + +* launch pricing models +* early revenue analysis +* adoption-friction detection +* introductory offers +* pricing-page variant comparison +* basic customer segmentation +* early margin analysis + +--- + +## 6.4 Growth + +Customer base and usage expand. + +Primary questions: + +* Which segments are most valuable? +* Which customers expand? +* Which pricing model scales? +* Which usage metrics correlate with value? +* Which packages increase adoption and revenue? + +Supported capabilities: + +* segmentation analysis +* expansion revenue analysis +* usage-based pricing analysis +* packaging optimization +* pricing model simulation +* LTV comparison +* churn and retention analysis +* commitment and discount evaluation + +--- + +## 6.5 Maturity + +The product has stable demand and known customer segments. + +Primary questions: + +* How should margin be optimized? +* How should plans be packaged? +* Which customers are underpriced or overpriced? +* Which discounts are economically justified? +* Which pricing model best supports retention? + +Supported capabilities: + +* margin optimization +* plan consolidation +* customer-level profitability analysis +* pricing governance +* discount policy modeling +* renewal pricing +* portfolio pricing +* dynamic recommendation + +--- + +## 6.6 Saturation + +Growth slows and competition increases. + +Primary questions: + +* How can market position be defended? +* Which bundles improve retention? +* Which segments remain attractive? +* Which price changes create risk? +* Which offers should be simplified? + +Supported capabilities: + +* competitive repricing analysis +* bundle evaluation +* retention pricing +* churn-risk pricing analysis +* portfolio comparison +* migration offers +* customer cohort analysis + +--- + +## 6.7 Decline + +The product is being harvested, replaced, migrated, or retired. + +Primary questions: + +* Should the product be maintained, migrated, harvested, or sunset? +* Which customers should be moved to another offer? +* Which price supports long-tail maintenance? +* Which commitments should no longer be accepted? + +Supported capabilities: + +* sunset pricing +* migration pricing +* long-tail profitability analysis +* contract risk analysis +* simplified maintenance pricing +* customer transition offers + +--- + +# 7. Product Scope + +Adaptive Pricing shall provide a practical product framework for pricing intelligence, pricing model design, simulation, recommendation, and execution. + +## 7.1 In Scope + +Adaptive Pricing shall support: + +* pricing hypothesis management +* pricing model definition +* pricing lifecycle modeling +* cost floor analysis +* value range exploration +* market competition analysis +* pricing experiment design +* customer segment analysis +* usage and cost attribution +* LTV modeling +* pricing simulation +* pricing recommendation +* customer-tunable pricing +* constraint evaluation +* payment-provider synchronization +* audit and explanation of pricing decisions + +## 7.2 Out of Scope + +Adaptive Pricing shall not become: + +* only a billing system +* only a Stripe wrapper +* only a pricing research document collection +* only a dashboard +* only a dynamic pricing tool +* only a discount calculator +* only a SaaS subscription manager + +Billing providers remain execution backends. + +Adaptive Pricing owns the pricing intelligence, pricing model, constraints, and lifecycle logic. + +--- + +# 8. Target Users + +## 8.1 Primary Users + +* founders +* builders +* product owners +* SaaS operators +* platform operators +* marketplace operators +* community operators +* pricing strategists +* revenue operators +* customer success teams +* sales teams +* AI agents assisting with product and pricing decisions + +## 8.2 Secondary Users + +* finance teams +* business analysts +* growth teams +* product marketers +* investors +* procurement advisors +* implementation partners + +--- + +# 9. Key User Needs + +Users need to: + +* reason about pricing before the product is finished +* make pricing assumptions explicit +* compare alternative pricing models +* understand cost floors +* estimate value ranges +* evaluate market alternatives +* choose value metrics +* identify economically valid discounts +* avoid accidental margin destruction +* expose pricing flexibility safely +* understand customer trade-offs +* operationalize pricing decisions without manual provider setup +* explain pricing recommendations to stakeholders + +--- + +# 10. Core Product Capabilities + +## 10.1 Pricing Hypothesis Management + +The system shall allow users to capture, structure, evaluate, and refine pricing hypotheses. + +A pricing hypothesis may relate to: + +* customer segment +* value proposition +* willingness to pay +* cost structure +* competition +* lifecycle phase +* pricing model +* commitment level +* discount rule +* usage metric +* outcome metric +* payment terms +* customer preference + +Each hypothesis should have: + +* statement +* rationale +* affected offering +* lifecycle phase +* confidence level +* evidence +* related experiments +* status +* decision history + +--- + +## 10.2 CostFloor Modeling + +The system shall help users understand the minimum economically viable pricing boundary. + +CostFloor shall consider: + +* fixed costs +* variable costs +* payment-provider fees +* support cost +* onboarding cost +* infrastructure cost +* third-party API cost +* human effort +* working capital +* risk buffer +* target minimum margin + +CostFloor shall not be treated as the final price. + +It is a lower economic boundary. + +--- + +## 10.3 ValueRange Exploration + +The system shall help users estimate and refine the range of prices that may be justified by customer value. + +ValueRange may be informed by: + +* customer interviews +* willingness-to-pay research +* observed usage +* customer outcomes +* saved cost +* generated revenue +* reduced risk +* time saved +* emotional value +* community value +* switching cost +* strategic importance + +--- + +## 10.4 MarketCompetition Modeling + +The system shall help users compare an offering against alternatives. + +Alternatives may include: + +* direct competitors +* indirect competitors +* manual workarounds +* internal build options +* open-source alternatives +* agency or consulting substitutes +* doing nothing +* existing customer workflows + +MarketCompetition should influence pricing strategy but not mechanically determine price. + +--- + +## 10.5 Pricing Model Definition + +The system shall allow users to define pricing models from reusable primitives. + +Supported primitives should include: + +* fixed fee +* subscription +* one-time fee +* setup fee +* usage meter +* included usage +* overage +* credits +* prepaid packages +* volume tiers +* graduated tiers +* stairstep tiers +* minimum commitment +* annual commitment +* contract duration +* discount +* rebate +* bundle +* feature package +* support package +* SLA package +* outcome fee +* success fee +* cancellation flexibility +* payment term adjustment + +--- + +## 10.6 Customer-Tunable Pricing + +The system shall allow sellers to expose selected pricing parameters as customer-tunable. + +Customer tuning may include preferences such as: + +* lower monthly base price +* higher included usage +* lower usage price +* stronger budget predictability +* higher flexibility +* lower upfront payment +* lower long-term cost +* higher support level +* shorter contract +* longer commitment +* prepaid usage +* volume discount + +Customer tuning shall not produce arbitrary discounts. + +When a customer changes tunable parameters, the system shall solve remaining non-fixed parameters so that seller economics remain valid. + +A tuned model shall be valid only if it satisfies seller-defined constraints. + +--- + +## 10.7 Comparable Customer LTV Evaluation + +The system shall support a seller-side metric tentatively named: + +`average_comparable_customer_lifetime_value` + +This metric estimates expected lifetime value for a customer under a given pricing configuration compared with similar customers, segments, usage expectations, risk profiles, and contract conditions. + +Customer-tuned pricing configurations shall be evaluated against a reference model: + +`most_favorable_predefined_model` + +A customer-tuned model should only be valid if: + +```text +average_comparable_customer_lifetime_value(tuned_model) +>= average_comparable_customer_lifetime_value(most_favorable_predefined_model) + × required_improvement_factor +``` + +The required improvement factor shall be configurable by the seller. + +--- + +## 10.8 Boundary Condition Evaluation + +The system shall evaluate pricing configurations against explicit boundary conditions. + +Boundary conditions may include: + +* cost floor +* minimum margin +* minimum turnover +* minimum commitment +* payment-provider fees +* expected usage variance +* support effort +* onboarding effort +* contract duration +* churn risk +* default risk +* upfront investment risk +* capital lockup +* operational capacity +* service-level risk +* abuse risk +* compliance constraints +* tax constraints +* accounting constraints +* customer segment eligibility +* sales approval thresholds +* maximum discount exposure + +Boundary conditions shall be inspectable, testable, and explainable. + +--- + +## 10.9 Pricing Simulation + +The system shall allow users to simulate pricing models before execution. + +Simulations should support: + +* expected revenue +* expected cost +* gross margin +* contribution margin +* cost per customer +* revenue per customer +* LTV +* churn sensitivity +* usage sensitivity +* payment fee sensitivity +* customer segment mix +* adoption assumptions +* risk scenarios +* discount exposure +* capacity pressure + +Simulation results shall be comparable across pricing models. + +--- + +## 10.10 Recommendation Engine + +The system shall generate pricing recommendations based on observed data, hypotheses, lifecycle stage, constraints, and simulations. + +Recommendations may include: + +* increase price +* decrease price +* change pricing model +* introduce usage-based component +* introduce minimum commitment +* reduce discount +* add plan tier +* remove plan tier +* introduce annual commitment +* add credit package +* add overage +* change included usage +* segment customers differently +* run pricing experiment +* collect more evidence before changing price + +Recommendations shall include rationale, confidence, risks, and supporting evidence. + +--- + +## 10.11 Pricing Execution + +The system shall translate validated pricing models into payment-provider artifacts. + +Payment providers may include: + +* Stripe +* Paddle +* Chargebee +* Lago +* Orb +* m3ter +* custom billing systems + +For Stripe, the system should eventually support automated management of: + +* products +* prices +* recurring subscriptions +* metered usage prices +* usage records +* tiers +* coupons +* discounts +* subscription configurations +* invoices +* billing periods +* tax-relevant metadata +* product metadata +* lifecycle states + +The Adaptive Pricing model shall remain the source of truth. + +Payment-provider state shall be generated, synchronized, reconciled, and audited. + +--- + +# 11. Functional Requirements + +## 11.1 Pricing Knowledge + +### FR-001 + +The system shall maintain a registry of pricing hypotheses. + +### FR-002 + +The system shall maintain a registry of offerings. + +### FR-003 + +The system shall maintain a registry of customer segments. + +### FR-004 + +The system shall maintain a registry of pricing models. + +### FR-005 + +The system shall maintain a registry of pricing experiments. + +### FR-006 + +The system shall maintain a registry of pricing observations. + +--- + +## 11.2 Lifecycle Support + +### FR-010 + +The system shall assign lifecycle phases to offerings. + +### FR-011 + +The system shall recommend pricing activities based on lifecycle phase. + +### FR-012 + +The system shall allow lifecycle phase transitions to be recorded. + +### FR-013 + +The system shall preserve pricing history across lifecycle phases. + +--- + +## 11.3 Cost, Value, and Competition + +### FR-020 + +The system shall model fixed costs. + +### FR-021 + +The system shall model variable costs. + +### FR-022 + +The system shall model payment-provider fees. + +### FR-023 + +The system shall calculate CostFloor. + +### FR-024 + +The system shall capture ValueRange assumptions. + +### FR-025 + +The system shall capture MarketCompetition assumptions. + +### FR-026 + +The system shall associate evidence with cost, value, and competition assumptions. + +--- + +## 11.4 Pricing Models + +### FR-030 + +The system shall define pricing models using composable primitives. + +### FR-031 + +The system shall distinguish fixed, seller-controlled, customer-tunable, calculated, and constrained parameters. + +### FR-032 + +The system shall version pricing models. + +### FR-033 + +The system shall compare pricing model versions. + +### FR-034 + +The system shall mark pricing models as draft, experimental, active, deprecated, or retired. + +--- + +## 11.5 Customer-Tunable Pricing + +### FR-040 + +The system shall allow sellers to expose selected parameters for customer tuning. + +### FR-041 + +The system shall calculate dependent parameters when customer-tunable parameters change. + +### FR-042 + +The system shall reject tuned configurations that violate seller constraints. + +### FR-043 + +The system shall explain why a tuned configuration is valid or invalid. + +### FR-044 + +The system shall compare tuned configurations with predefined reference models. + +--- + +## 11.6 LTV and Economic Evaluation + +### FR-050 + +The system shall calculate expected revenue for a pricing model. + +### FR-051 + +The system shall calculate expected cost for a pricing model. + +### FR-052 + +The system shall calculate expected margin for a pricing model. + +### FR-053 + +The system shall estimate customer lifetime value. + +### FR-054 + +The system shall support average comparable customer LTV calculations. + +### FR-055 + +The system shall support configurable required improvement factors. + +--- + +## 11.7 Boundary Conditions + +### FR-060 + +The system shall define boundary conditions. + +### FR-061 + +The system shall evaluate pricing configurations against boundary conditions. + +### FR-062 + +The system shall explain boundary condition violations. + +### FR-063 + +The system shall support approval thresholds for risky configurations. + +--- + +## 11.8 Simulation + +### FR-070 + +The system shall simulate pricing models under configurable assumptions. + +### FR-071 + +The system shall compare multiple pricing scenarios. + +### FR-072 + +The system shall simulate customer segment mixes. + +### FR-073 + +The system shall simulate usage variance. + +### FR-074 + +The system shall simulate discount exposure. + +### FR-075 + +The system shall simulate lifecycle-specific strategies. + +--- + +## 11.9 Recommendations + +### FR-080 + +The system shall generate pricing recommendations. + +### FR-081 + +Recommendations shall include rationale. + +### FR-082 + +Recommendations shall include confidence. + +### FR-083 + +Recommendations shall include risks. + +### FR-084 + +Recommendations shall reference supporting observations. + +### FR-085 + +Recommendations shall distinguish between suggested research, suggested simulation, suggested model change, and suggested execution. + +--- + +## 11.10 Execution Integrations + +### FR-090 + +The system shall maintain payment-provider-independent pricing definitions. + +### FR-091 + +The system shall map internal pricing models to payment-provider artifacts. + +### FR-092 + +The system shall synchronize active pricing models with payment providers. + +### FR-093 + +The system shall detect drift between internal model state and provider state. + +### FR-094 + +The system shall maintain an audit trail of pricing execution. + +--- + +# 12. Non-Functional Requirements + +## 12.1 Explainability + +All recommendations, simulations, validations, and rejections shall be explainable. + +## 12.2 Auditability + +Pricing decisions and changes shall be reproducible from recorded data, assumptions, and model versions. + +## 12.3 Provider Independence + +Pricing models shall not depend structurally on a single payment provider. + +## 12.4 Extensibility + +New pricing primitives, constraints, integrations, and lifecycle playbooks shall be addable without redesigning the core model. + +## 12.5 Trust Preservation + +Adaptive pricing shall avoid hidden exploitation. Customer-facing adaptive pricing should be understandable, bounded, and based on explicit trade-offs. + +## 12.6 Regulatory Awareness + +The system shall support governance and audit features needed for fair, explainable, and compliant pricing practices. + +## 12.7 Agent Readiness + +The system shall be usable by both humans and AI agents. Important concepts, assumptions, and decisions shall be represented in structured, machine-readable form. + +--- + +# 13. Conceptual Data Model + +## Offering + +Represents a product, service, community, marketplace, platform, or bundle that may be priced. + +## Pricing Hypothesis + +Represents a testable belief about value, cost, competition, customer behavior, or pricing mechanics. + +## Pricing Model + +Represents a structured commercial model composed of pricing primitives. + +## Pricing Primitive + +Represents an atomic pricing component such as subscription, usage meter, discount, commitment, or outcome fee. + +## Pricing Parameter + +Represents a configurable value inside a pricing model. + +## Boundary Condition + +Represents an economic, operational, legal, or strategic constraint. + +## Pricing Experiment + +Represents a structured attempt to validate or falsify pricing hypotheses. + +## Pricing Observation + +Represents evidence collected from customers, usage, revenue, interviews, market research, or experiments. + +## Customer Segment + +Represents a group of customers with similar needs, economics, risk, usage, or willingness to pay. + +## Pricing Scenario + +Represents a simulated pricing configuration under explicit assumptions. + +## Pricing Recommendation + +Represents a suggested action based on evidence, simulation, lifecycle state, and constraints. + +## Payment Execution Mapping + +Represents the translation from internal pricing model to payment-provider artifacts. + +--- + +# 14. Pricing Governance + +Adaptive Pricing shall support governance for pricing changes. + +Governance capabilities should include: + +* model versioning +* approval workflows +* discount policies +* customer communication requirements +* grandfathering rules +* lifecycle-state rules +* risk thresholds +* provider synchronization logs +* audit history +* rollback support + +Pricing changes should not be treated as casual configuration edits. + +They are product, business, customer, and trust decisions. + +--- + +# 15. Success Metrics + +Adaptive Pricing is successful if users can: + +* capture pricing assumptions early +* convert assumptions into pricing hypotheses +* design experiments to validate willingness to pay +* understand cost floors +* estimate value ranges +* compare market alternatives +* define pricing models structurally +* simulate economic outcomes +* expose safe customer pricing choices +* preserve seller economics under customer tuning +* identify invalid discounts +* generate explainable pricing recommendations +* execute pricing models through payment providers +* keep pricing models auditable and lifecycle-aware + +Business success may be measured by: + +* improved pricing confidence +* reduced manual pricing work +* fewer invalid discounts +* better margin visibility +* better lifecycle fit of pricing models +* improved customer conversion +* improved retention +* improved average comparable customer LTV +* faster pricing experiment cycles +* lower payment-provider configuration errors + +--- + +# 16. Product Boundaries + +Adaptive Pricing should integrate with payment providers, analytics systems, CRM systems, product usage systems, and financial tools. + +However, it should not become a replacement for all of them. + +The product’s durable center is: + +> pricing knowledge, pricing reasoning, pricing simulation, pricing governance, and pricing execution mapping. + +--- + +# 17. Development Horizons + +## Horizon 1 — Pricing Knowledge Foundation + +Establish the core model: + +* offering +* lifecycle phase +* pricing hypothesis +* cost floor +* value range +* market competition +* pricing model +* pricing primitive +* pricing observation + +## Horizon 2 — Simulation and Recommendation + +Add: + +* pricing scenarios +* lifecycle-aware playbooks +* economic simulation +* recommendation logic +* risk and constraint explanation + +## Horizon 3 — Customer-Tunable Pricing + +Add: + +* tunable parameter surfaces +* constraint solving +* comparable customer LTV comparison +* safe customer preference trade-offs + +## Horizon 4 — Execution Automation + +Add: + +* Stripe integration +* additional payment-provider integrations +* provider drift detection +* automated price creation +* subscription and usage billing synchronization + +## Horizon 5 — Auto-Regulating Pricing + +Add: + +* continuous market value exploration +* automated recommendation loops +* bounded adaptive pricing +* pricing health monitoring +* lifecycle-aware auto-regulation +* trust-preserving dynamic pricing + +--- + +# 18. Strategic Positioning + +Adaptive Pricing should become the pricing capability layer for offerings built on +this framework and related product ecosystems. + +It should also be useful as a standalone product for builders, founders, SaaS teams, platform operators, marketplace creators, and AI-assisted business development workflows. + +The product should occupy the space between: + +* pricing research +* product strategy +* revenue operations +* billing infrastructure +* customer preference modeling +* economic simulation +* payment-provider automation + +Its defining claim: + +> Adaptive Pricing helps builders discover, validate, optimize, and execute pricing models from the first idea to the final lifecycle stage. + +--- + +# 19. Open Questions + +The following questions require further research and refinement: + +* How should ValueRange be estimated before customer data exists? +* Which pricing experiment formats should be supported first? +* How should average comparable customer LTV be defined precisely? +* Which pricing primitives should be considered canonical? +* How should customer-tunable pricing be presented without confusing customers? +* Which fairness rules should constrain adaptive pricing? +* How should lifecycle phase transitions be detected? +* How should payment-provider drift be reconciled? +* How should pricing recommendations be validated before execution? +* Which pricing decisions should require human approval? +* How should AI agents participate in pricing exploration safely? + +--- + +# 20. Summary + +Adaptive Pricing is a lifecycle-spanning pricing intelligence and execution platform. + +It helps builders reason from early pricing hypotheses to executable pricing models. It supports cost floor analysis, value range exploration, market competition modeling, pricing experiments, simulations, recommendations, customer-tunable pricing, and payment-provider execution. + +The product is not merely about automating billing. + +It is about making pricing an explicit, adaptive, evidence-based, and trustworthy product capability. + diff --git a/projects/coulomb-pricing/README.md b/projects/coulomb-pricing/README.md index aab684c..1dec1ae 100644 --- a/projects/coulomb-pricing/README.md +++ b/projects/coulomb-pricing/README.md @@ -4,6 +4,9 @@ Project-specific material for the Coulomb Social Economic Observatory MVP. This directory holds implementation artifacts, integrations, and documentation that apply to the Coulomb deployment only. Generic adaptive-pricing framework concepts -belong in the repository root (`INTENT.md`, `research/`, `registry/`, etc.). +belong in the repository root (`INTENT.md`, `docs/`, `research/`, `registry/`). -Tracked workplan: `workplans/ADAPTIVE-WP-0002-economic-observatory-mvp.md`. \ No newline at end of file +**Execution tracking:** `workplans/ADAPTIVE-WP-0002-economic-observatory-mvp.md` + +**Strategic positioning:** Adaptive Pricing is the pricing capability layer for +Coulomb offerings and related product ecosystems. \ No newline at end of file