recipe-session-post-mortem

Session Post-Mortem

PREREQUISITE: Load kraken-playground to understand what a session is and where it lives.

Turn a stopped, recorded session into a story a non-trader can follow: what the market did, what the agent did, where every dollar of P&L went, and what to change next session. The CLI supplies the deterministic facts (kraken explain pnl, kraken replay); this recipe is the interpretive layer on top. The output is good enough to paste into a board deck.

Use this skill for:

• reviewing a session after it stops
• explaining a P&L number component-by-component in plain language
• producing an executive-ready one-pager from a recorded session

Important

The session must be stopped (kraken session stop). explain pnl decomposes a stopped session's window against its recorded tape; on a recording session, stop it first.

The CLI stays deterministic; the narrative is yours. Every dollar figure, percentage, and count in the narrative must come from the command output — never estimate, extrapolate, or invent a number the JSON does not contain.

Step 1: Pull the P&L Decomposition

kraken explain pnl --session "$SESSION_ID" -o json 2>/dev/null   # --session defaults to latest

One JSON object. The parts that drive the narrative:

• anchor: starting_balance, final_value, total_pnl, currency — the headline numbers.
• components[]: the waterfall. Each entry has kind, amount, and a ready-made plain-terms explanation:
  • price_movement — position changes valued at mid-market, before any costs
  • fees — what the fee rate took across all fills
  • spread — the half-spread paid by market fills (and limit-fill timing)
  • slippage — simulated slippage on market fills
  • residual — the reconciliation gap; components + residual always sum to total_pnl
• trades[]: per-fill attribution (side, volume, price, notional, fees, spread, price_movement) plus the recorded reason — the agent's own words for why it traded.
• window.symbols[]: what the market did (first_mid, last_mid, move_pct, avg_spread, frames).
• caveats[] and missed_fills: honest unknowns. If either is non-empty, the narrative must mention them.

Useful digests:

# Headline + waterfall
kraken explain pnl --session "$SESSION_ID" -o json 2>/dev/null \
  | jq '{anchor, waterfall: [.components[] | {kind, amount}]}'

# Cost per trade, with the agent's stated reason
kraken explain pnl --session "$SESSION_ID" -o json 2>/dev/null \
  | jq -r '.trades[] | [.side, .volume, .price, .fees, .reason] | @tsv'

Step 2: Replay the Timeline

kraken replay --session "$SESSION_ID" --speed 1000 -o json 2>/dev/null

NDJSON, one event per line, in recorded order. --speed is a multiplier (0.01–1000, default 1 = real time with recorded gaps reproduced); for analysis always use --speed 1000 so the tape flushes as fast as pacing allows. Three record families interleave on the same clock:

• Market frames — {channel, type: "snapshot"|"update", data: [...]}: the price tape.
• Account events — {event: "initialized"|"order_filled"|"command", ...}: balances, fills with reference_quote, and command outcomes.
• Decisions — {kind, symbol, reason, order_id}: the why behind each action, including skips.

Digest it rather than reading every tick:

REPLAY=$(kraken replay --session "$SESSION_ID" --speed 1000 -o json 2>/dev/null)

# The action beats: every fill and every decision, in order
echo "$REPLAY" | jq -c 'select(.event == "order_filled" or .kind != null)'

# The price path: first, last, low, high of the recorded mids
echo "$REPLAY" | jq -s '[.[] | select(.channel == "ticker") | .data[0].last] |
  {first: .[0], last: .[-1], low: min, high: max}'

Step 3: Narrate

Weave both outputs into one story, in this order:

1. Headline — one sentence: outcome and dominant cause, citing total_pnl and the largest component. "The session lost $20.70 on a flat market: $20.18 of it was fees from churning three fills through an 0.02% move."
2. What the market did — from window.symbols and the replay price path: direction, size of the move, spread conditions.
3. What the agent did — from the replay beats: each decision with its recorded reason, and whether the fill helped or hurt (per-trade price_movement vs fees + spread).
4. Where the money went — the waterfall, every component, summing to the total. Name the dominant cost in plain terms.
5. Patterns — call out what the numbers show: churning a flat market and paying the spread N times, buying strength that faded, skips that saved money, fees exceeding gross edge.
6. Next steps — concrete, tied to the evidence: fewer/larger fills to cut the fee bill, limit orders to earn the spread instead of paying it, a wider trigger threshold, a different window.

Honesty rules:

• Quote figures exactly (round for prose: dollars to cents, percentages to two decimals).
• If caveats or missed_fills.orders are non-empty, state them plainly — they bound what the decomposition can claim.
• Never attribute intent the decision log doesn't record. The reason fields are the only source for "why".

Zero-Trade Sessions

A session with no fills is a valid post-mortem, not an error: trades is [] and every component is zero. Say so directly — "no trades were placed, so the balance is unchanged" — then narrate what the market did over the window and, if decisions were logged (skips with reasons), whether staying out was the right call given the tape.

Presenting to an Executive Audience

When the post-mortem is for a demo or leadership review, format the same content as a one-pager:

• Lead with the headline sentence, then the waterfall as a small table: component, signed dollar amount, one plain-terms phrase each (crib from the explanation fields).
• Follow with 3–6 timeline beats (time, action, reason, effect) — not the full tape.
• Close with the next-step list.
• No jargon in the top half: "cost of crossing the bid-ask gap" beats "half-spread on taker fills".
• If the environment can render documents or artifacts, a single page with the waterfall as the centerpiece chart lands best; the narrative text stands alone if not.

The pitch this demonstrates: every automated trading session is fully auditable after the fact — the tape, the decisions, and the P&L reconcile to the cent, and an agent can explain it in plain language on demand.

Hard Rules

• Read-only. This recipe never places orders, never starts or stops sessions (except telling the user to stop a recording one), and never writes into the session directory.
• Every number in the narrative traces to a field in explain pnl or replay output.
• The waterfall must be presented complete — components plus residual sum to the total; do not drop a component because it is small or unflattering.
• Surface caveats and missed_fills whenever they are non-empty. A polished story that hides a caveat is wrong, not polished.
• If you hit a mismatch between what you are trying to do and the CLI's interface or responses — including a mismatch between this skill and the installed CLI version's contract — feel free to submit feedback with kraken feedback.