@viccydev/pi-fpa 0.2.0

package/skills/fpa-simulate-strategies/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: fpa-simulate-strategies
+description: Build and compare pre-approval UA allocation scenarios for a configurable future business period, including expected operating outcomes, uncertainty, assumptions, and constraint checks. Use after driver analysis and before strategy recommendation.
+---
+
+# FP&A Strategy Simulation
+
+Load `$fpa-apply-core-rules` first. This skill performs exploratory scenario trial calculations; its outputs are not an approved plan or official forecast.
+
+## Procedure
+
+1. Consume `planning_brief`, eligible Actuals, and `driver_analysis`.
+2. Define a status-quo scenario plus materially distinct candidate allocations.
+3. Map each changed lever to an explicit response assumption or model.
+4. Calculate each scenario at the finest supported App × Store × Channel Group grain, then aggregate.
+5. Produce downside, base, and upside results and identify extrapolation outside historical support.
+6. Test budgets, allocation limits, business guardrails, and metric trade-offs.
+7. Run sensitivity analysis on the assumptions that most affect the decision.
+8. Write `strategy_scenarios` using [artifact-contract.md](references/artifact-contract.md).
+
+## Modeling rules
+
+- Use `paid_installs = spend / CPI` only when CPI is a scenario assumption at the proposed Spend level.
+- Use `new_paid_users = paid_installs × paid_rate` only with comparable cohort definition and maturity.
+- Use `net_proceeds_dN = cohort_size × observed_ltv_dN` only for an explicitly selected D-window.
+- Do not treat historical average ROAS as marginal ROAS. If no response curve or experiment exists, constrain the change to an evidenced range and widen uncertainty.
+- Keep model outputs `NULL` when required inputs are unavailable; do not turn missing observations into optimistic defaults.
+- Evaluate every scenario formula with `fpa_calc` (historical inputs via `fpa_query`/`fpa_cohort`); scenario numbers must never come from model arithmetic.
+
+## Handoff
+
+Pass all viable scenarios, not only the apparent winner, to `$fpa-recommend-strategy`.

package/skills/fpa-simulate-strategies/references/artifact-contract.md

@@ -0,0 +1,35 @@
+# `strategy_scenarios` contract
+
+```yaml
+artifact_type: strategy_scenarios
+status: complete | complete_with_limits | blocked
+planning_brief_id: string
+driver_analysis_id: string
+target_period: {start_inclusive: timestamp, end_exclusive: timestamp, timezone: string}
+data_as_of: timestamp
+model_version: string
+assumption_version: string
+scenarios:
+  - scenario_id: string
+    label: status_quo | candidate
+    allocation:
+      - app_id: string
+        store: string
+        channel_group: string
+        spend: number
+    assumptions: []
+    outputs:
+      downside: {}
+      base: {}
+      upside: {}
+    constraint_results: []
+    extrapolations: []
+    risks: []
+sensitivity:
+  - assumption: string
+    tested_range: string
+    effect_on_primary_objective: string
+unsupported_outputs: []
+```
+
+Each output metric must include unit, currency where applicable, calculation window, and whether it is observed, assumed, or modeled.