JeffBrines/openfpa

# Segment Roll-Up (generated for Fox Factory)

## Why this skill exists

The standard openfpa skills model a single entity. Fox Factory reports **three
segments** (PVG, AAG, SSG) and, under ASU 2023-07, discloses **net sales and
Adjusted EBITDA per segment - but not segment COGS or operating income**
(`.fpa/business-profile.md`). The base engine has no segment concept, so this
skill was generated to bridge the gap. It cites these profile facts:

- Three reportable segments; segment metric is **Adjusted EBITDA**, not gross profit.
- Segment-level working capital, debt, and tax are **not disclosed** - those stay
  consolidated. So segments drive the P&L down to Adjusted EBITDA only; the
  consolidated layer owns everything below.

# Backtest & Learn (Operate)

## Overview

The model should get measurably better at this business over time. This skill
scores past forecasts against the company's actuals, surfaces what keeps missing,
and proposes improvements a human ratifies. The objective metric is reconciliation
error against the user's own books (`pyfpa.score_forecast`) - the FP&A analog of a
validation loss.

**Core principle:** self-experimenting, but never self-promoting. The AI may run
and discard bounded challengers autonomously; a human approves replacement of
the champion. Everything learned lives as plain files in `.fpa/`.

# Board Briefing (Operate)

## Overview

Turn forecast output into a board/investor-grade briefing: the headline numbers, the cash story, what changed, and the risks - as markdown and Excel. Make the operator look like they have a CFO.

**Core principle:** A board wants the story and the three things that matter, not a data dump.

## When to use

- Board decks, investor updates, lender packages
- "Summarize the forecast for leadership"

## Workflow

# Capture a Correction (Operate)

## Overview

A human reviewing a forecast is the highest-signal feedback there is - they catch
structural errors and domain knowledge the backtest can't see, and catch them *now*.
This skill turns that into durable memory: a typed correction in `.fpa/corrections/`
that grounds every future forecast.

**Core principle:** the human is the authority; capture, confirm interpretation once,
then it persists. Everything is plain markdown the user owns.

## The three correction types

# Cash Runway (Operate)

## Overview

Build the 13-week direct-method cash forecast - the operator's near-term liquidity view. Schedule the known weekly receipts and disbursements, show the **raw** cash position (no automatic LOC draws), and report the trough and first negative week.

**Core principle:** Show the unfinanced position. A visible shortfall is the whole point - it sizes the credit line.

## When to use

- "When do we run out of money?" / runway questions
- Sizing or stress-testing a working-capital line
- Lumpy near-term cash events (inventory buys, tax, payroll cadence)

# CFO Judgment

## Overview

A forecast that's arithmetically correct can still be wrong about reality. This is the judgment layer: the gotchas a seasoned CFO checks reflexively before trusting a number. Consult it during **any** analysis - close, briefing, runway, scenario.

**Core principle:** Numbers lie by omission. Before reporting a figure, ask what's *not* in it yet.

## The reflexes

| Trap | What a CFO checks |
|------|-------------------|
| **Pre-close months look great** | COGS and accruals post late. A high gross margin in a not-yet-closed month is usually unposted cost, not real profit. Exclude pre-close months from conclusions, or flag them loudly. |
| **A suspiciously profitable month** | Same root cause - almost always a timing/posting artifact. Reconcile before celebrating. |

# Configure Actuals & Data Sources (Phase 2)

## Overview

Connect the model to real data - from wherever it lives. openfpa is **not married to a connector**: everything normalizes to one shape (`{account: amount}`), and where no built-in path exists, **you build the ingestion for this source**. That's the job, not a workaround - see `examples/foxfactory/pull_edgar.py`, a SEC-EDGAR adapter the agent wrote from scratch because no built-in one existed.

**Core principle:** one normalized shape regardless of source, so the engine never cares where the numbers came from - and the agent meets the data where it is.

## The data can come from anywhere

- **Local spreadsheets** (always works, no credentials). A P&L, balance sheet, AR/AP aging, or inventory export. `pyfpa.read_pl_csv(path)` reads any two-column `Account, Amount` CSV (handles `$`, commas, `(parens)` negatives) → `{account: amount}` - it is generic, not P&L-only. For **richer tables** (aged AR/AP buckets, item-level inventory) there is no rigid reader by design: parse the file to what the model needs - derive **DSO** from AR aging, **DIO** from inventory, **DPO** from AP aging.
- **A live accounting system via MCP** - the cleanest live path. If a **QuickBooks** or **NetSuite** MCP server is connected, pull the trial balance / P&L / balance sheet through it and map the result to `{account: amount}`. openfpa never handles credentials - the MCP server owns auth.
- **A live system via API** - build a company-specific connector around the
  source API and its actual report shape. The functions in `pyfpa.io.adapters`

# Live-Formula Excel Model (Operate)

## Overview

Finance professionals ultimately want a workbook where changing an assumption
recalculates the model. This skill produces one from the model structure, with
named assumption cells and real formulas, then proves it reproduces the engine
before it ships. Static value dumps stay with `forecast_to_excel`; this skill
is for living models.

**Core principle:** no workbook ships unverified. The workbook is generated
from the model, never hand-edited values.

## The standard model

# Learn the Business (Phase 0)

## Overview

Before scaffolding any model, learn the business. This produces two artifacts: a **durable business profile** that every other openfpa skill reads first, and - where the standard skills don't fit - **bespoke skills/agents generated for this specific company**. The toolkit re-tools itself per business instead of forcing a generic template.

**Core principle:** A forecast is only as good as the business understanding behind it. Encode that understanding once, explicitly, so it grounds everything downstream.

## When to use

- A new company is being onboarded into openfpa
- You're asked to "build us a model" / "understand our business" before forecasting
- An existing `.fpa/business-profile.md` is missing or stale

# Monthly Close (Operate)

## Overview

Fold the latest actuals into the model, refresh the forward forecast from the last closed position, and explain the variance. The output is a *narrative*, not just a variance table - what changed, why, and what it means forward.

**Core principle:** A close that only reports numbers isn't done. The value is the explanation.

## When to use

- Month-end actuals are available
- "How did we do vs plan?" / reforecast requests

## Workflow

# Portfolio Learn (Loop B)

## Overview

Loop A makes the model better at one client. This makes your *practice* compound:
client #10 starts smarter than client #1 because your library carries what generalized
across #1–9. Everything is local - your own book, on your own machine.

**Core principle:** self-improving, never self-ratifying - propose, you accept. The
objective metric is cross-client: does a pattern learned on some clients fail to
degrade the *others*' backtest?

## Setup

# Company Research Loop

## Purpose

Run an AutoResearch-style loop against the company's own forecast history. The
AI may generate, test, and discard challengers autonomously. Only promotion to
the active champion requires human approval.

## Memory And State

- `.fpa/research/objective.yaml`: company-specific metrics, weights, hard checks,
  minimum improvement, and complexity penalty.
- `.fpa/research/*.epoch.yaml`: every hypothesis and evaluated epoch, including
  discarded candidates.

# Scaffold a Model (Phase 1)

## Overview

Turn a company's financials into a runnable `pyfpa` config. Read the business profile first (see **fpa-learn-business**), infer the chart-of-accounts → model-line mapping, and write a validated `EntityConfig` YAML following openfpa conventions. Output a runnable skeleton plus an explicit list of assumptions to confirm.

**Core principle:** Convention over invention. Map the real numbers onto the existing engine shape; don't design a new one.

## When to use

- A trial balance / P&L (CSV, XLSX, or pasted) needs to become a forecast model
- Onboarding follow-on after `.fpa/business-profile.md` exists

## Workflow

# SKU Profitability

> **Generated skill (example).** This is the kind of bespoke skill `fpa-learn-business`
> proposes when the business profile says *"product company with a discrete SKU set."*
> It lives in `skills/generated/` - in a real engagement it would be written into the
> client's repo after human approval, citing the profile facts that justify it (here:
> a limited-SKU D2C brand where per-product economics drive the mix decision).

## Overview

The channel-level forecast tells you the business is healthy; it doesn't tell you *which products* carry it. This skill computes per-SKU economics and the Pareto curve so you can see the 80/20, find margin-dilutive SKUs, and make cut/reprice/push calls.

**Core principle:** Revenue flatters; margin and contribution decide. Rank by gross profit, not by sales.