delta-minimizer

name

delta-minimizer

description

Investigate ONE specific discrepancy between our wallet's position and a copy-trade target's position on Polymarket. Use whenever the user says 'why are we on the wrong side', 'why is our VWAP off', 'why didn't we mirror that fill', 'delta on market X', 'minimize delta', 'investigate copy-trade gap', '/delta-minimizer', or points at a single market/event on the dashboard and asks what happened. The copy-trade algorithm is known to have fundamental bugs; the skill's job is to find ONE bug, prove it with cited evidence, and stop.

Δ-Minimizer

We copy-trade a target wallet (e.g. swisstony) on Polymarket. Our positions should match theirs. Every divergence is a bug. The algorithm has known fundamental issues — your job is to find ONE, prove it, file it, move on.

Required reading BEFORE you query anything

You are expected to already understand the system. If you don't, read these — they are short and load-bearing:

• docs/spec/poly-copy-trade-execution.md — mirror-side rules, decision-ledger contract, MirrorPositionView (per-condition cache; our_token_id = OUR dominant side), error codes, lifecycle, sizing surfaces. Branch decision (post-bug.5048) is target-dominance-driven — see the "Branch decision" table + skip-precedence + TARGET_DOMINANCE_DRIVES_BRANCH / NEVER_PAY_ABOVE_TARGET_VWAP / NO_SELL_IN_MIRROR / OPTION_C_TOLERATES_MULTI_TARGET invariants. When investigating wrong-side / wrong-size Δ, always check state.target_position side fractions, not just our position. The dashboard reads current-position-read-model.ts (chain-classified by poly_market_outcomes), NOT MirrorPositionView — never claim UI behavior without verifying the actual read model.
• docs/spec/poly-tenant-and-collateral.md — per-tenant wallets, USDC.e (deposit) vs pUSD (the ONLY currency the CLOB spends), authorizeIntent pre-place gate (grants/caps, NOT balance), v0 default caps. errorCode=insufficient_balance ≠ "we ran out of money"; it specifically means the wallet has USDC.e but not pUSD (TEN:712).
• nodes/poly/app/src/features/copy-trade/plan-mirror.ts + types.ts — the MirrorReason enum (below_target_percentile, followup_position_too_small, position_cap_reached, already_resting, layer_scale_in, target_dominant_other_side, vwap_floor_breach, etc.) is in code, not the spec. decideMirrorBranch + analyzeTargetDominance + targetVwapForToken are the load-bearing helpers.

Canonical CLOB errorCode enum (EXEC:693): insufficient_balance | insufficient_allowance | stale_api_key | invalid_signature | invalid_price_or_tick | below_min_order_size | empty_response | http_error | unknown.

Discipline (read this twice)

1. One discrepancy per pass. Not three. Not a top-K list. The user names ONE market, ONE token, ONE side — you investigate that. If they hand you several, ask which one first.
2. Every claim must be backed by a specific DB row or a specific Loki log line, pasted in your response. No "likely cause." No "probably." No agent-summarized narrative — those hallucinate conditionIds and event titles. If you can't paste the evidence, you don't make the claim.
3. Verify the basics before theorizing. Confirm the conditionId. Confirm the tokenId. Confirm whose wallet. Confirm timestamps.
4. Drive through to logs in the same pass — never stop on a Postgres-only read. Decision rows with outcome='error', receipt=null tell you NOTHING about why. The actual errorCode lives on the pino log line, not the DB row. A pass is not complete until you have both: the decisions/fills row AND the matching Loki line(s) for any non-placed outcome. If Loki retention has aged out (>7d), say so explicitly — don't infer.
5. One verifiable finding per pass. End the pass with: (a) the question, (b) the evidence rows/lines, (c) the conclusion, (d) the next narrower question. ONE finding does not mean ONE query — it means you keep digging until the finding is provable, then stop.
6. Never theorize about UI behavior. If the answer depends on what the dashboard shows or hides, read nodes/poly/app/src/.../current-position-read-model.ts (and the API route serving the panel) and paste the relevant code. Don't speculate that the UI "collapses" or "hides" anything.

Evidence sources — these are the ONLY ones allowed

Postgres (via Grafana proxy)

Datasource UID for prod: cogni-production-poly-postgres. Helper: scripts/grafana-postgres-query.sh '<SQL>' --env production --node poly. Read-only (SELECT/WITH/SHOW/EXPLAIN).

Schema gotchas to know up front:

• poly_copy_trade_decisions.decided_at (NOT created_at) is the timestamp column, timestamp with time zone — compare with to_timestamp(<seconds>), not bare epoch ints.
• poly_copy_trade_decisions.target_id is a UUIDv5 derived from (billing_account_id, target_wallet) and does NOT FK to poly_copy_trade_targets.id. Joining the two tables on target_id returns zero rows. To find decisions for swisstony, filter by intent->>'target_wallet' or grab the v5 id from a sample row first.
• intent->>'market_id' has the form prediction-market:polymarket:0xCONDITION_ID, not the bare condition_id. intent->>'position_token_id' is often null on new_entry decisions; the actual token_id is in the fill_id string after the second :.
• poly_trader_wallets.kind: copy_target for the wallets we mirror, cogni_wallet for our own.

Most relevant tables (schemas in nodes/poly/packages/db-schema/src/):

Table	What it holds	Key cols
poly_copy_trade_targets	Targets we mirror	id, target_wallet, mirror_filter_percentile, mirror_max_usdc_per_trade, created_at, disabled_at
poly_trader_wallets	Wallet directory with labels (swisstony, RN1, our cogni_wallet)	id, wallet_address, kind, label
poly_trader_fills	Every fill we've seen for any tracked wallet (target's AND ours)	id, trader_wallet_id, source, native_id, condition_id, token_id, side, price, shares, size_usdc, observed_at
poly_copy_trade_decisions	One row per (target fill → our decision). The truth of what the mirror chose to do. receipt=null is normal on outcome='error' — the WHY is in Loki.	id, target_id (UUIDv5), fill_id, outcome (placed/skipped/error), reason, intent (jsonb), receipt (jsonb), decided_at
poly_copy_trade_fills	Our placed orders	PK (target_id, fill_id), market_id, client_order_id, order_id, status, attributes (jsonb)
poly_market_outcomes	Market resolution (chain-authoritative)	(condition_id, token_id), outcome, payout, resolved_at

SQL templates:

-- 0. Find swisstony's deterministic target_id (sample one of its decisions)
select target_id, count(*) from poly_copy_trade_decisions
where intent->>'target_wallet' = '0x204f72f35326db932158cba6adff0b9a1da95e14'
group by target_id;

-- 1. All fills on a condition with wallet labels
select w.label, w.kind, f.side, f.token_id, f.price, f.shares, f.size_usdc, f.observed_at, f.native_id
from poly_trader_fills f join poly_trader_wallets w on w.id = f.trader_wallet_id
where f.condition_id = '0xCONDITION_ID_HERE'
order by f.observed_at asc;

-- 2. Every decision the mirror made for one target on one market (note the prefix on market_id)
select d.decided_at, d.fill_id, d.outcome, d.reason,
       d.intent->>'outcome' as outc, d.intent->>'side' as side,
       d.intent->>'fill_price_target' as p, d.intent->>'fill_size_usdc_target' as sz,
       d.intent->>'position_branch' as branch
from poly_copy_trade_decisions d
where d.target_id = '<UUIDv5 from query 0>'
  and d.intent->>'market_id' = 'prediction-market:polymarket:0xCONDITION_ID_HERE'
order by d.decided_at asc;

-- 3. Recent non-placed decisions, grouped by (reason, intent.outcome)
select reason, outcome, intent->>'outcome' as outc_name, count(*) as n
from poly_copy_trade_decisions
where decided_at > now() - interval '24 hours' and outcome != 'placed'
group by 1, 2, 3
order by n desc;

Loki (literal history tracing)

Helper: scripts/loki-query.sh '<logql>' [minutes_back=30] [limit=200]. Standard selector for prod poly node: {env="production",service="app",pod=~"poly-node-app-.*"}. Retention is ~7 days — if your incident is older, say so and don't fabricate.

component labels (pino) you'll actually use:

• component="mirror-pipeline" — the decision engine. Every non-placed decision row has a matching level=50 log here carrying the real errorCode (which is NEVER in decisions.receipt).
• component="copy-trade-executor" — the CLOB place call. Look here for raw CLOB rejection bodies.
• component="polymarket-ws-source" — wallet-watch ingestion (target's fills entering our system).
• component="order-reconciler" — order-status sync back to DB.
• component="mirror-job" — outer scheduler.

Queries that actually return something:

# What did mirror-pipeline say for a given fill_id? (substring match on the fill_id)
scripts/loki-query.sh '{env="production",service="app"} | json | component="mirror-pipeline" |~ "FILL_HEX_PREFIX"' 1440 200

# Every place attempt on a tokenId in the last day
scripts/loki-query.sh '{env="production",service="app"} | json | component="copy-trade-executor" |~ "TOKEN_ID_HERE"' 1440 200

# Recent placement errors with their errorCode (most useful)
scripts/loki-query.sh '{env="production",service="app"} |~ "placement_failed"' 1440 50

Example walkthrough — one pass

User: "Our wallet shows UNDER 41 sh on Chelsea v Nott Forest O/U 3.5 while swisstony shows OVER 31k sh. Why are we on the wrong side?"

Step 1 — verify the basics. Look up wallets in poly_trader_wallets (label = swisstony / our cogni_wallet). Find our 41.28-sh position via poly_trader_fills aggregation (group by condition_id, token_id, filter on share count + vwap). Pull the exact condition_id and token_id. Cross-check: did the target trade BOTH outcomes on this condition? select … where condition_id=? group by token_id — many "wrong-side" appearances are the target having scalped both sides; the apparent inversion is then a sizing/execution issue, not a side-flip.

Step 2 — pull every decision the mirror made for that target on that condition. Use query template #2. Read them in time order. Categorize each by outcome + reason. If all placed decisions are on token X and the target's actual fills are on token X, the mirror's side-selection is fine. If you see a meaningful number of outcome='error' rows, that is the central failure, not whichever side won.

Step 3 — drive through to Loki in the SAME pass. decisions.receipt is null on errors; the errorCode only lives on the Pino line. Paste the JSON line and read the errorCode. Cross-reference against the CLOB enum and the collateral spec. Only then write up.

Step 4 — write up. Question, 3–5 rows/lines of raw evidence, conclusion grounded in those rows, next narrower question. Do not theorize about UI behavior — if the UI is in play, read the read-model code.

What this skill does NOT do

• No aggregate scorecards, no |Δ| histograms, no failure-mode taxonomies until a single case is fully proven.
• No auto-filing of work items. After a proven finding, the user (or you on explicit ask) files a concrete bug with evidence pasted inline.
• No reading from /api/v1/poly/wallet/execution — it aggregates server-side and obscures the underlying rows.
• No subagent reports as primary evidence. Subagents can fetch raw rows/lines; you read them yourself.
• No claims about what the dashboard "shows" or "hides" without reading the read-model file. MirrorPositionView has a dominant-side selection; the dashboard read model may or may not — find out by reading code, not by guessing.
• No ending a pass with "Postgres said X, want me to check Loki?" If Loki is the next step, just run it. Pareto baby step = one finding, not one query.