modules/sales-plan/skills/sales-plan/SKILL.md

---
name: sales-plan
description: Use when Vera must create a reviewed forward-looking sales Plan from monthly Actuals and confirmed commercial or FX assumptions.
---

## Output Location Rule

Never write run outputs inside this Git workspace or a published folder. Use
only the Studio Archive run path described below.

## Client engagement gate

Select one Studio Archive client and engagement, import the reviewed Actuals
and case inputs, then call `prepare_studio_client_workflow` with workflow ID
`sales-plan`. Pass the returned `client_engagement_path` as
`--client-engagement` to preparation and execution. Use only the context's run
folder; cross-engagement inputs and arbitrary outputs are rejected.

Start the prepared run before preparation. After the last output write, call
`finalize_studio_client_workflow` and declare every physical file with a stable
artifact ID, relative path, concrete purpose, audience, and media type. Review
the closed declaration, then call `complete_studio_client_workflow`; record
`failed` or explicitly cancel an abandoned run instead of treating a partial
directory as a result.

# Vera Plan

Use this workflow to create a forward-looking sales Plan from reviewed monthly
Actuals. This is planning and scenario modelling, not historical financial
analysis or financial due diligence.

The deterministic recipe can apply percentage assumptions to:

- units;
- unit price;
- gross sales;
- discount;
- COGS;
- the reporting-currency-per-transaction-currency FX rate.

Vera interprets the commercialista's request and prepares the structured
assumption read-back. The commercialista confirms the meaning, scope, periods,
currency direction, priority, same-driver overlap behavior, and the basis for
explicit discount or COGS changes. The engine owns exact arithmetic, collision
checks, reconciliation, output hashes, and replay evidence.

## Chat-first assumption review

Keep a small assumption set in chat. Inspect the source columns and actual
dimension members before interpreting the request. For example:

> In China unit sales go up 8%, but the dollar weakens 5% against the euro.

Read it back before calculation:

| ID | Driver | Exact scope | Change | Effective periods | Priority |
| --- | --- | --- | ---: | --- | ---: |
| A1 | units | `country=China` | +8% | all mapped Plan periods | 100 |
| A2 | USD/EUR rate | `transaction_currency=USD` | -5% | all mapped Plan periods | 100 |

Show matched source members and affected rows when inspection can establish
them. Ask the commercialista to confirm or correct the table. Do not treat a
broad conversational statement as approval of a materially different
structured assumption.

Resolve only ambiguities that change the result:

- “sales increase” must become units, unit price, or gross sales;
- v2 accepts percentage changes only;
- the FX rate is reporting-currency units per transaction-currency unit;
- source and Plan FX rates must remain exactly `1` when transaction currency
  equals reporting currency;
- a 5% weaker USD against EUR is `-5%` for USD rows when EUR is reporting;
- scopes must match exact source dimension members;
- same-driver overlaps require the reviewed case to choose `priority` or
  `compound`;
- `priority` applies only the highest-priority matching assumption and fails
  closed when multiple winners have equal priority;
- `compound` applies every matching same-driver assumption by multiplying each
  reviewed percentage effect; priority and assumption ID make the ledger order
  deterministic;
- gross-sales changes cannot overlap unit or unit-price changes on one row;
- unit and unit-price assumptions require a positive source Units value;
- an explicit discount or COGS change must state whether it applies to the
  `actual_amount` or the `sales_adjusted_amount`;
- v2 preserves observed sparse Actual rows and does not impute zero sales,
  missing customer-months, or seasonality.
- Missing optional units, discounts or COGS remain unavailable. Dependent net
  sales, margins and incomplete summary totals remain blank, with source row
  IDs in reconciliation warnings. Known values in unaffected groups remain
  usable; a recorded zero is a known value.

For a large assumption set, prepare the same review table in Markdown or case
JSON and review it in batches. A separate HTML workbench is not part of v2.

## Codex-Native Run UX

Before running helper scripts, identify the material choices that would change
the Plan: source scenario, target periods, reporting currency, dimensions,
driver meaning, exact scope, FX direction, assumption priority, same-driver
overlap behavior, discount and COGS assumption bases, and review audience.
Ask only those unresolved choices in chat and wait when their answer would
materially change execution. Generate choices from the actual inputs; do not
propose dimensions, drivers, currencies, planning rules, or output packages
unless the facts cue them.

Default output policy: produce the complete normal Plan scenario, assumption
ledger, summary, reconciliation, evidence manifest, and execution receipt when
the reviewed case supports them. Natural outputs are not choices to propose.

1. Start with a visible markdown checklist covering intake, source inspection,
   dependency check, assumption review, deterministic Plan run,
   reconciliation, professional review, and delivery.
2. Show a Run Intake table with the case and source paths, output folder,
   Actual and Plan scenarios, period mapping, reporting currency, dimensions,
   reviewed assumptions, and unresolved items.
3. Show a compact Decision Table for unresolved driver meanings, scopes,
   periods, FX direction, priorities, collisions, exclusions, or evidence
   limitations.
4. Before long-running or write-heavy work, show an execution checkpoint with
   the command intent, inputs, output folder, and expected artifacts. Seek
   approval only under the approval boundary stated below.
5. End with an Artifact Card listing every delivered file, its purpose, Plan
   and reconciliation status, unresolved professional-review items, and next
   action. When useful, write `codex_run_review.md` beside the run artifacts.
   Never edit plugin source or generated ZIPs during a user-data run.

## Run workflow

Reserve explicit approval for external, destructive, approval-sensitive, or
materially unresolved steps. The assumption-table confirmation is required
because it fixes a material planning choice; ordinary local inspection and
validation should continue without an extra approval step.

1. Establish the Actual source, reporting currency, Actual-to-Plan period
   mapping, dimensions, assumptions, and review audience.
2. Run the dependency check from the module root:

```bash
python scripts/check_dependencies.py
```

The declared `requirements.txt` is standard-library only. Do not install
undeclared packages.
3. Prepare the reviewed case contract. It must bind the source hash, period
   mapping, scenario codes, reporting currency, dimension columns, default
   discount and COGS behavior, same-driver overlap behavior, explicit discount
   and COGS assumption bases, structured assumptions, and professional-review
   receipt.
4. Run:

```bash
python scripts/run_plan.py \
  --case <client-run-output>/case.json \
  --client-engagement <client_engagement_path> \
  --output-dir <client-run-output>/plan
```

5. Stop on failed reconciliation or any unmatched scope, unsupported driver,
   stale or changed source, ambiguous priority collision, incompatible driver
   combination, or missing metric needed by an assumption.
6. Read `model_use_manifest.json` after the run. For ordinary model-led review,
   use the assumption ledger, summary, reconciliation, and prepared-evidence
   lineage listed there. Do not load the complete row-level scenario by
   default. When a professional question requires row detail, request exact
   matches and only the needed prepared-scenario columns:

```bash
python scripts/model_use.py \
  --manifest <client-run-output>/plan/model_use_manifest.json \
  --reason <specific-professional-question> \
  --source-row-id <exact-source-row-id> \
  --where <column=exact-value> \
  --column <needed-output-column> \
  --client-engagement <client_engagement_path>
```

   Supply at least one exact row ID or filter and at least one output column.
   The helper scans the complete sealed scenario locally and returns every
   exact match without sampling. It never reopens the raw Actual file.
7. Deliver the Plan scenario and review artifacts. A passed run proves exact
   execution and reproducibility; it does not approve the assumptions or the
   resulting Plan.

## Natural outputs

- `sales_plan_scenario.csv`;
- `assumption_application_ledger.csv`;
- `scenario_summary.csv`;
- `reconciliation.json`;
- `prepared_evidence_manifest.json`;
- `model_use_manifest.json` and any explicitly requested
  `model_drilldowns/scenario_rows_*.json` artifacts;
- `plan_execution_receipt.json`.

Every result remains `report_ready=false` until professional review.

## Plugin Improvement Feedback

After completing substantive work, note technical defects or workflow gaps
without client or source details. Keep the improvement note local to chat or run artifacts.

## Financial report presentation

For comparable monetary results, show the baseline and comparison values together
with both absolute variance in the reporting currency and percentage variance.
Use the existing workflow's reporting charts and structured tables, with units,
periods, aligned numbers, explicit totals and source-supported interpretation.
Do not finish a substantive report with only a compact chat table when normal
artifacts are supported. Use the existing generated report and chart artifacts;
do not invent a custom renderer or manufacture a baseline or monthly breakdown.
Keep zero/negative-base percentages explicitly unavailable where misleading,
retain amount differences, and establish favorable/adverse meaning by account.
A user-requested quick answer or reduced output remains valid.