# OKR Integration — Systems Dynamics Model

> Pulse doesn't just *list* OKRs. It models them as a **causal graph** so that every Key Result has a clear, explicit story for how moving it grows the org. If a KR can't articulate that story, it doesn't belong on the board.

## Premise

Most OKR tools treat objectives as a flat list. The result: KRs get set, KRs get hit, and nobody can explain why the company didn't grow. Pulse's premise is that an OKR system is only useful if it functions as a **causal model of the business** — improving any leaf metric should be traceable, through explicit feedback mechanisms, to one of a small set of overarching outcomes.

## Two layers

The causal model lives at two layers, edited by different people on different cadences:

| Layer       | Nodes                              | Edges                                 | Authored by              | Cadence    |
|-------------|------------------------------------|---------------------------------------|--------------------------|------------|
| Strategic   | Super KRs + AccountabilityAreas    | Area → Super KR, Area → Area, Super KR → Super KR (loops) | **Founders** (`is_founder` Roles) | Slow — quarterly to yearly |
| Operational | KRs + Projects + Tasks + Leads     | KR → Area (typical), KR → Super KR (escape hatch), KR → KR | Anyone with nexus access | Fast — weekly to quarterly |

The strategic layer is the **scaffolding** — the firm's standing theory of how the fund works. It changes when leadership reconsiders strategy, not when a quarter's KRs come due. The operational layer hangs off it: each new KR declares which Area it advances, and that Area in turn drives a Super KR. Tasks and projects then attach to KRs.

Why split them: the systems-dynamics model degrades fast if every contributor can edit the top-level scaffolding to fit the quarter's KRs. Locking the scaffolding to founders keeps the theory of change durable across many quarters of operational churn. The operational layer stays open so day-to-day work can move freely without leadership review.

The causal-map dashboard surfaces both layers with a toggle: **Strategic** (Super KRs + Areas only) reads the firm's theory at a glance; **Full** overlays the operational KRs hanging off each Area.

## The three Super KRs

Outliers' overarching outcomes are fixed and small. Every other node in Pulse exists to drive one (or more) of these:

| Slug    | Super KR            | Why it's a super KR |
|---------|---------------------|---------------------|
| `aum`   | Assets Under Management | Stock metric. The size of the engine — drives fee revenue and gravitational pull for new capital. |
| `roi`   | Return on Investment    | Quality metric. What we deliver per dollar of AUM — the reason capital stays and compounds. |
| `brand` | Brand Recognition       | Flow-multiplier. Lowers the cost of acquiring AUM and recruiting; raises optionality on every other initiative. |

These three are not arbitrary — they are stocks that **feed each other**: better ROI grows AUM, larger AUM funds brand investment, stronger brand attracts AUM and talent which in turn improves ROI. (See "Reinforcing loops" below.)

## How a KR earns its place

Every `KeyResult` in Pulse must declare at least one `drives` link, transitively reaching a Super KR. Three valid targets, in preference order:

1. An **AccountabilityArea** (typical) — the KR advances a strategic-layer Area, which itself drives a Super KR.
2. Another **KR** (sometimes) — useful for KR→KR causal chains where one operational metric is a leading indicator of another.
3. A **Super KR** directly (escape hatch) — allowed but discouraged. Most KRs that bypass Areas are either revealing a missing Area in the strategic layer or are vanity metrics. The dashboard flags KR-direct-to-Super-KR links as candidates for an Area-layer addition.

A `drives` link is not just a pointer — it carries the **mechanism** in plain English. The field is a structured object (`{ prose, coefficients? }`) so quantification can land later without a migration; v1 writes only `prose`:

```
{
  target_type: "area",
  target_id: "area_lp_communications_cadence",
  polarity: "+",
  mechanism: {
    prose: "Hitting 4 investor events per quarter directly advances the LP communications cadence Area, sustaining touchpoint frequency that the renewal mechanism depends on.",
    coefficients: null   // reserved — see "Mechanism quantification (forward-looking)" below
  },
  strength: "moderate",
  lag: "quarters"
}
```

Areas in turn carry the same `drives` shape, pointing at Super KRs (or other Areas). The two-layer chain a typical KR follows: `KR → Area → Super KR`.

If you can't write the `prose` paragraph, the KR isn't ready. Pulse should make this friction visible — a KR with no `drives` is flagged in the UI and cannot be marked "active" for a quarter.

### Mechanism quantification (forward-looking)

`mechanism` is qualitative-only in v1. We model it as an object from day one because some mechanisms are obviously coefficient-shaped — *"1 long-form note → ~2k newsletter signups"*, *"1pp NPS lift → ~$Xm AUM"* — and once enough quarters of validation history exist, attaching coefficients enables scenario simulation (sliders on the causal map, "if we hit 6 events instead of 4, what's the AUM impact range?"). v1 ships without that surface. The shape is forward-compatible so coefficients can land incrementally without touching every existing record.

## Polarity and feedback loops

Each link has a polarity:

- **`+`** — improving the source moves the target in the **same direction** (improving NPS *raises* AUM)
- **`-`** — improving the source moves the target in the **opposite direction** (reducing time-to-onboard *raises* AUM, but the *metric* "time-to-onboard" going down is what helps, hence `-` polarity from the metric to AUM)

A loop in the causal graph is a **feedback loop**:

- **Reinforcing (R)** — even number of `-` edges (including zero). Compounds in one direction. Most growth stories live here.
- **Balancing (B)** — odd number of `-` edges. Self-correcting / goal-seeking. Often the constraints (capacity, churn) we need to design around.

The data model treats `drives` as a DAG to keep storage simple — you can't literally write a cycle. The "loop" exists at the **dashboard / visualization layer**: when two KRs each point at the same SuperKR through different paths, or when a SuperKR's growth is articulated as funding investment in a downstream KR (e.g. "AUM growth → more brand budget → brand → AUM"), Pulse surfaces that as a named loop on the org diagram.

## What Pulse does with this

Concrete UI/data implications, in roughly priority order:

1. **Causal map view** — directed graph rooted at the 3 Super KRs with two layers (Strategic / Full toggle). Strategic mode shows only Super KRs and Areas + their drives — the firm's standing theory at a glance. Full mode overlays the operational KRs hanging off each Area. Edges carry polarity, strength, lag. Filter by BU or FU to scope.
2. **Orphan detector** — surfaces any KR whose transitive `drives` doesn't reach a Super KR. Three flavors of orphan: badly framed, vanity metric, or revealing a missing Area in the strategic layer that leadership should consider adding.
3. **Bypass detector** — KR-direct-to-Super-KR links (the escape hatch). Allowed but flagged as candidates for an Area-layer addition; over time, the dashboard nudges leadership to either add a covering Area or accept the direct link as legitimate.
4. **Change-impact preview** — when someone proposes a new KR, the editor asks them to draw the link before saving. The picker biases toward existing Areas; pointing at a Super KR directly raises the bypass flag.
5. **All-hands prep** — for each Super KR, the prep view rolls up: "this quarter, the following Areas claim to drive AUM (with their declared mechanisms), and these KRs operate within those Areas." Surfaces both layers separately so leadership can ask theory-of-change questions cleanly.
6. **Loop callouts** — when the graph contains a named reinforcing or balancing loop (curated, not auto-detected at first), the dashboard highlights it: "Brand → AUM → Brand budget → Brand. Currently reinforcing. Strength: moderate."

## Worked example

A KR like *"Publish 12 long-form research notes by Q4"* attaches to the Area it advances rather than directly to a Super KR:

```
drives: [
  {
    target_type: "area",
    target_id: "area_research_output_quality",
    polarity: "+",
    mechanism: {
      prose: "12 long-form notes per year is the cadence the Research Output Quality Area was scoped around. Below this rate, the Area's own drives links to Brand weaken; above it, the long-tail compounding effect kicks in.",
      coefficients: null
    },
    strength: "moderate",
    lag: "weeks"
  }
]
```

Then the *Area* — `Research Output Quality` — declares its own drives (strategic layer, founder-authored):

```
drives: [
  { target_type: "super_kr", target_id: "brand", polarity: "+",
    mechanism: { prose: "Long-form research output is the primary brand surface for target LPs. Note volume × note quality × distribution drives recognition and warm inbound.", coefficients: null },
    strength: "strong", lag: "quarters" },
  { target_type: "super_kr", target_id: "roi", polarity: "+",
    mechanism: { prose: "Internal research quality bounds the floor on investment decisions; better research → better picks.", coefficients: null },
    strength: "moderate", lag: "quarters" }
]
```

Now the research KR isn't just "publish 12 notes" — it has a declared theory of how those notes advance an ongoing Area, and the Area in turn carries the org's standing theory of how that work shapes Brand and ROI. At quarter-end, if the notes shipped but the Area's own metrics didn't move, both layers can be re-examined separately: the operational mechanism (was 12 the right cadence?), or the strategic mechanism (does this Area really drive Brand the way we claimed?).

## Open questions

- **Decay of belief:** if a `drives` link's predicted impact doesn't show up over 2–3 quarters, do we mark the link as "weakened" / "disproven" rather than just delete it? Carrying that history teaches the org which theories of change actually work.
- **KR vs. project drivers:** today only KRs declare `drives`. Should Projects too, or do they inherit from the KRs they're tied to? (Note: Areas and Leads now also declare `drives` — same shape as KRs.)
- **Editing cadence on the strategic layer:** how often do founders revisit Area drives mechanisms? Probably annual review with mid-year touchpoints, but worth deciding once Areas are populated.
- **Bypass-flag tolerance:** how many KR-direct-to-Super-KR links is "too many"? When the dashboard surfaces N+ bypasses, leadership should treat it as a signal that the Areas layer is missing coverage. The N is open.