AgapHost/adolf/DESIGN-proactive-prioritization.md

# DESIGN — Proactive action impact/cost prioritization (kb#123)

Status: **draft, for review** — written 2026-07-22
Owner: alvis · Written with Claude
Scope: kanboard Adolf task **#123**. This is a design/ruleset only — no wiring
into `openclaw.json`, no code. Claude implements it in a follow-up task.

Related, not duplicated here:
- **#122** (utility/ROI metrics via Langfuse) — that's the after-the-fact
  "was Adolf worth it" readout across all of Adolf's spend. This doc is the
  **before-the-fact gate** on one specific class of spend: proactive sends.
  #122's Langfuse data is a candidate future input to the acceptance-rate term
  below (§3.3), but this design does not depend on #122 landing first.
- **#124** (proactive cadence / cron schedule) — decides **when Adolf looks**
  (daily/weekly/monthly audit cadence, adapted to quota). This design decides
  **whether a specific candidate action fires** once #124 (or an ad-hoc
  trigger, e.g. reacting to a calendar change) has already produced one.
  #124 is the scheduler; this is the gate every candidate passes through
  regardless of what triggered it.
- **#125** (feedback loop) — this design's acceptance-probability term (§3.3)
  is a **consumer** of #125's feedback log. #125 is not built yet; §5 below
  specifies exactly what it needs to log, as a dependency, not an assumption.

---

## 1. Problem

Adolf can generate a proactive message (reminder, nudge, digest item) from
several places: the cadence jobs in #124, a reactive trigger (calendar event
changed, HA sensor fired, a task went overdue), or background reasoning
noticing something. Not every candidate should be sent — some are low-value,
some are redundant with something already said, some cost real Kimi quota to
formulate and the window is nearly exhausted.

This design is a **gate function**: given a candidate proactive action, decide
fire / suppress / defer, using a score computed from four inputs the task
description names, plus a threshold that scales with remaining quota.

## 2. Where the gate sits

```
 [trigger: #124 cadence job | reactive event | background noticing]
                     |
                     v
          candidate proactive action
          (draft content + metadata)
                     |
                     v
        ┌─────────────────────────┐
        │   IMPACT/COST GATE      │   <-- this design
        │   (score, threshold)    │
        └─────────────────────────┘
              |            |
           fire         suppress / defer
              |            |
       send via Matrix   log decision + reason
       log outcome slot   (no send; feedback loop
       for #125           has nothing to attach to)
```

The gate is a pure function of the candidate + current state. It does not
decide *what* to consider sending (#124's job) or *how* to learn from
responses (#125's job) — only whether a given candidate clears the bar right
now.

## 3. Scoring model

For each candidate action `a`, compute:

```
score(a) = (benefit(a) * accept_prob(a) * urgency(a)) / cost(a)
```

Ratio form, not a weighted sum: cost is a genuine denominator (token cost is
literally what you're trading against benefit), and the three numerator terms
are gates on each other, not additive alternatives — a high-benefit,
low-acceptance-probability action *should* be suppressed even if urgency is
high, not partially compensated the way a sum would allow. All four terms are
normalized to comparable ranges as defined below so no single term dominates
by scale alone.

### 3.1 Benefit — `benefit(a) ∈ [0, 1]`

"How important is this to the user, if accepted." Estimated by Adolf itself
(the model doing the drafting) using a small fixed rubric — this is a
judgment call, not a measurement, so keep the rubric coarse enough to be
stable across repeated runs:

| Band | Value | Examples |
|---|---|---|
| Critical | 1.0 | Hard deadline today/tomorrow, safety/health-adjacent, financial penalty if missed |
| High | 0.7 | Real deadline this week, blocks another person, irreversible if missed |
| Medium | 0.4 | Useful reminder, no hard deadline, low cost if ignored |
| Low | 0.15 | "Might be nice to know", trivia-adjacent, no consequence |

Adolf assigns the band as part of drafting the candidate (one extra field in
the same generation pass — no separate LLM call). This is inherently noisy;
it is corrected over time by the acceptance-probability term (§3.3), which is
grounded in actual logged outcomes rather than self-assessment.

### 3.2 Cost — `cost(a) ∈ (0, 1]`, token cost normalized

Raw cost is estimable *before* sending: `tokens_estimate(a)` = prompt tokens
to formulate (system + context already loaded for the turn, since it's
piggy-backing on an existing generation) + estimated output tokens for the
message itself. For a message that requires its **own** dedicated Kimi call
(true incremental cost) vs. one riding along inside an already-scheduled
cadence turn (near-zero marginal cost), these are very different costs — the
estimate must distinguish "marginal call I wouldn't otherwise make" from
"free byproduct of a call happening anyway":

```
cost_tokens(a) = marginal_prompt_tokens(a) + marginal_output_tokens(a)
```

where `marginal_*` is 0 (or near-0, e.g. a few output tokens) if the action
rides inside a scheduled #124 audit turn that would run regardless, and the
full call cost if it requires spinning up a fresh Kimi turn.

Normalize against a reference ceiling (a "typical expensive proactive send",
empirically ~2-3K tokens per the #122 baseline measurements of ~32.8K for a
full reply turn — a standalone proactive nudge should be far cheaper than a
full conversational turn, since it's one-directional with no back-and-forth):

```
cost(a) = clamp(cost_tokens(a) / COST_CEILING, floor=0.05, cap=1.0)
```

`COST_CEILING` = 3000 tokens (tunable constant, revisit once #122 gives real
distributions). The 0.05 floor stops a literally-free riding action from
dividing by ~0 and producing a runaway score — even "free" actions carry some
opportunity cost (attention, message-count against the 60/5h ceiling, not
just tokens).

### 3.3 Acceptance probability — `accept_prob(a) ∈ [0, 1]`

**This term has no data source yet.** It depends entirely on #125 (feedback
loop) being built and logging outcomes. Until then, use a flat prior:

```
accept_prob(a) = 0.5   # uninformative prior, pending #125
```

Once #125 logs `(action_class, outcome)` pairs (see §5's exact schema
requirement — this design does not invent history, it specifies what must
exist), compute a per-class empirical rate with Laplace smoothing so a class
with zero or few samples doesn't overfit to noise:

```
accept_prob(class) = (accepted_count(class) + 1) / (total_count(class) + 2)
```

`class` is a coarse bucket, not per-message: e.g. `{calendar_reminder,
task_overdue, ha_anomaly, family_wiki_gap, digest_item, ...}` — one row per
class, not per exact message text, since exact-text history rarely repeats
but the class does. A candidate's class is assigned at draft time (same pass
as §3.1's benefit band).

Recency matters more than total count — a user who started dismissing
`calendar_reminder` last week should pull that class's rate down faster than
five-year-old acceptances prop it up. Use a decayed count (e.g. half-life of
30 days, or simply windowing to the trailing N=50 outcomes per class) rather
than an all-time average, once enough volume exists to make decay
meaningful.

### 3.4 Urgency — `urgency(a) ∈ [0, 1]`

Distinct from benefit: benefit is "how much it matters", urgency is "how soon
it stops being actionable". A time-decay curve against the nearest relevant
deadline (`due_at`) known for the candidate (calendar event start, task
`date_due`, HA-derived risk window):

```
hours_to_deadline = (due_at - now) in hours

urgency(a) =
    1.0                              if hours_to_deadline <= 1
    1.0 - 0.6 * (h - 1) / 23         if 1 < h <= 24     (1.0 -> 0.4 over the day)
    0.4 * exp(-(h - 24) / 168)       if h > 24          (decays over the following week)
    0.2                              if no deadline (informational-only action)
```

Concretely: something due within the hour scores 1.0, something due
tomorrow ~0.4-1.0 depending on how close, something a week out trails off
toward the 0.2 floor for undated nudges. This is a simple monotonic decay, not
a precise model — tune the constants once real cadence data exists (#124).

### 3.5 Putting it together

```
score(a) = (benefit(a) * accept_prob(a) * urgency(a)) / cost(a)
```

Range: numerator ∈ [0, 1], denominator ∈ [0.05, 1], so
`score(a) ∈ [0, 20]` in the degenerate cheapest/most-urgent/most-beneficial
case. In practice, typical scores cluster well below that ceiling — the
threshold (§4) is calibrated empirically against observed scores, not derived
analytically from the range.

## 4. Firing rule

```
fire(a)  iff  score(a) >= threshold(current_quota_state)
else          suppress(a)   # or defer(a), see below
```

### 4.1 Quota signal

Read `adolf-llm:8010/usage` (confirmed live shape, sampled 2026-07-22):

```json
{
  "weekly":   {"pct": 32, "used": 32, "limit": 100, "remaining": 68, "resets": "..."},
  "window_5h":{"pct": 79, "used": 79, "limit": 100, "remaining": 21, "resets": "..."},
  "stale": false
}
```

Use the **tighter** of the two windows — whichever pct is higher is the
binding constraint right now:

```
quota_pressure = max(weekly.pct, window_5h.pct) / 100      # ∈ [0, 1]
```

If `stale: true` (Kimi login/session broken, per the adolf-llm fallback
behavior), treat as `quota_pressure = 1.0` (most conservative) — an unknown
quota state should suppress non-critical sends, not fire them.

### 4.2 Threshold as a function of quota pressure

```
threshold(quota_pressure) = T_BASE + (T_MAX - T_BASE) * quota_pressure^2
```

- `T_BASE` = 0.3 — threshold when quota is abundant (pressure ~0): let most
  medium-benefit things through.
- `T_MAX` = 3.0 — threshold when quota is nearly exhausted (pressure ~1):
  only near-maximal score (critical benefit, high acceptance history, urgent,
  cheap) still fires.
- Squaring `quota_pressure` keeps the threshold flat and permissive through
  low-to-mid pressure (nothing changes until quota actually gets tight) and
  then rises steeply as the window approaches exhaustion — matching the
  actual failure mode (403 usage-limit) which is a cliff, not a slope.

This gives a single tunable curve with two constants, both revisitable once
#122 supplies real score distributions and false-negative/positive rates.

### 4.3 Fire / suppress / defer

- **fire**: send now.
- **suppress**: below threshold and no deadline pressure — drop it. Log the
  decision (§5) but do not re-surface it later; if it's still relevant, the
  next cadence pass (#124) will regenerate it as a fresh candidate with
  updated urgency.
- **defer**: below threshold *only because of quota pressure*, but
  `urgency(a) >= 0.8` (i.e., something time-critical got starved by a quota
  cliff, not by low benefit). Requeue for immediate re-evaluation once
  `quota_pressure` drops (next window reset, per `resets` timestamp in the
  usage payload) rather than silently dropping it. This is the one exception
  to "gate is stateless" — a deferred item carries state (its own candidate
  record) until it either fires or its deadline passes, at which point it is
  logged as a missed/expired suppression, not silently lost.

## 5. Dependency: what #125's feedback log must contain

This design's accept_prob term (§3.3) is inert without it. #125 owns building
the collection mechanism (reactions, "+/-/неактуально" replies); this design
only specifies the **shape** the gate needs to consume, so the two tasks
don't diverge on schema:

```
proactive_outcome {
  action_class:   string   # matches the class taxonomy in §3.3, e.g. "calendar_reminder"
  sent_at:        timestamp
  benefit_band:   float    # the benefit(a) value used at send time, for later calibration
  cost_tokens:    int      # actual cost, for calibrating COST_CEILING
  urgency_at_send: float
  outcome:        enum { accepted, dismissed, ignored, irrelevant }
  responded_at:   timestamp | null
}
```

`ignored` (no response within some window, e.g. 24h) must be distinguished
from `dismissed` (explicit "−") — an ignored item is weaker negative signal
than an explicit rejection and should decay the acceptance rate less
aggressively. Without this distinction the Laplace-smoothed rate in §3.3
conflates "user didn't care" with "user was just busy."

Every **suppressed** and **deferred** candidate should also be logged (not
just fired ones) with `outcome: not_sent` — this is what lets a later audit
(#122) compute false-suppression rate (was a suppressed item actually needed?
only knowable in hindsight, e.g. if the same underlying deadline later caused
a problem) as well as false-fire rate.

## 6. Worked example

Candidate: "reminder that the Seafile SSL cert renews in 3 days" (from a
#124 daily cadence audit, riding along inside that scheduled call).

- `benefit`: Medium band → 0.4 (annoying if missed, not critical — auto-renew
  likely already configured, this is a check not a fire drill).
- `cost`: marginal — rides inside the already-running daily audit call, say
  ~150 marginal output tokens → `150/3000 = 0.05` → floored at 0.05.
- `accept_prob`: no #125 data yet → flat prior 0.5.
- `urgency`: `hours_to_deadline` = 72h → falls in the `h > 24` branch:
  `0.4 * exp(-(72-24)/168) = 0.4 * exp(-0.286) ≈ 0.4 * 0.751 ≈ 0.30`.

`score = (0.4 * 0.5 * 0.30) / 0.05 = 0.06 / 0.05 = 1.2`

At `quota_pressure = 0` (abundant quota), `threshold = 0.3` → **1.2 ≥ 0.3,
fires.** At `quota_pressure = 1` (window nearly exhausted, matching the
measured 79% 5h-window sample above, rounding up toward the cliff),
`threshold = 3.0` → **1.2 < 3.0, suppressed** (not deferred: urgency 0.30 is
well under the 0.8 defer bar) — correctly deprioritized under quota pressure
in favor of anything more urgent or already proven to land well.

## 7. Open parameters to tune post-implementation

Everything with a concrete numeric constant above (`COST_CEILING`, `T_BASE`,
`T_MAX`, the urgency decay constants, the defer bar) is a starting guess
consistent with the measurements already on hand (#122's token baseline, the
live `/usage` sample). None of it is load-bearing on the *shape* of the
model — only on where the dial sits. Revisit once:

- #125 supplies real `accept_prob` data (replacing the flat 0.5 prior is the
  single highest-value follow-up — everything else is a reasonable guess,
  this term is currently a placeholder).
- #122's Langfuse integration supplies real per-action token costs to
  recalibrate `COST_CEILING`.
- A few weeks of fire/suppress/defer logs (§5) exist to check the threshold
  isn't systematically over- or under-firing.

## 8. Acceptance check against kb#123

- Scoring formula with each term defined, ranged, and its estimation method
  stated: §3.
- Firing rule (fire only if impact/cost exceeds a threshold): §4.
- Threshold tunable to current quota, against the real `adolf-llm:8010/usage`
  signal: §4.1-4.2.
- Acceptance-probability term flagged as dependent on unbuilt history
  (#125), with the exact log schema it needs specified rather than
  fabricated: §3.3, §5.
- Cross-references to sibling tasks #122, #124, #125 without duplicating
  their scope: header + inline.