AGENT SKILL

order-lifecycle-safety

Idempotency, reconcile-before-retry, audit-before-forward and environment-proof preflight rules for any code or agent that places broker orders. Use when building or reviewing an order path, handling a timeout or unknown order outcome, adding client_order_id, deciding whether a retry is safe, or confirming paper vs live before sending an order.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 32
Forks
6

01 前言 Front Matter

name
order-lifecycle-safety
description
Idempotency, reconcile-before-retry, audit-before-forward and environment-proof preflight rules for any code or agent that places broker orders. Use when building or reviewing an order path, handling a timeout or unknown order outcome, adding client_order_id, deciding whether a retry is safe, or confirming paper vs live before sending an order.

02 资源文件 2

03 SKILL.md 正文

Order Lifecycle Safety

Pure markdown. No dependencies, no code to install. These are the rules an order path must own itself; do not assume an external approval gate exists.

1. Unique client_order_id on every order

  • Every order carries a client_order_id generated by your code, once, before the first send.
  • It must be unique per intended order and stable across retries of that same order.
  • Persist it (audit log) before sending, so a crash cannot lose it.
  • Respect broker length/charset limits: see references/broker-caveats.md.

2. Same terms vs different terms (REPLAY / ID_REUSED)

Repeat of an existing id Correct behaviour Label
Same id, same terms Return the first result; do not create a second order REPLAY
Same id, different terms Refuse; never mutate or resubmit under that id ID_REUSED

Implement this in your own layer (compare a hash of symbol, side, qty, type, price, TIF). Do not rely on the broker to do it; broker behaviour varies (see caveats).

3. Unknown outcome: reconcile before retry

A timeout, 5xx, dropped connection, or crash after send means the outcome is unknown, not failed.

  1. Mark the order UNKNOWN in the audit log.
  2. Look the order up by client id (or list recent orders and match).
  3. Found → adopt its status. Not found after the broker's lookup is known consistent → only then may you resend with the same client id.
  4. Lookup itself fails → stay UNKNOWN, alert a human. Never blind-retry.

4. Audit before forward

  1. Decide (allow/refuse).
  2. Write the decision, with the client id and terms, to an append-only audit log before forwarding.
  3. Forward to the broker.
  4. If forwarding raises or times out, append UNKNOWN (not FAILED) and go to section 3.
  5. Redact credentials from log lines.

If the audit write fails, do not forward: fail closed.

5. Environment-proof preflight

Never infer paper vs live from config, env var names, base URLs, or account-number shape. Config can be wrong or edited.

  • Before the first order of a session, read the environment back from the broker.
  • Prefer a call that states the environment/capabilities of the session (a session-capabilities call) over a bare auth-status call, which usually proves only that credentials work, not which environment they belong to.
  • Compare the broker's answer to the environment the operator intended. Match → proceed. Mismatch, missing field, or any ambiguity → refuse.
  • Re-run after any credential or endpoint change.
  • Whether a given broker exposes such a call is per-broker; see references/broker-caveats.md. If none does, treat the environment as unproven and require a human to confirm in a terminal the agent cannot reach.

Checklist

  • [ ] client id generated and persisted before send
  • [ ] REPLAY / ID_REUSED handled locally
  • [ ] audit entry written before forward; forward failure recorded as UNKNOWN
  • [ ] no retry without lookup by client id
  • [ ] environment read back from broker, ambiguity refuses

See references/ for tables.

04 同仓库更多 Skills

mphinance
mphinance/alpha-skills

order-lifecycle-safety

Idempotency, reconcile-before-retry, audit-before-forward and environment-proof preflight rules for any code or agent that places broker orders. Use when building or reviewing an order path, handling a timeout or unknown order outcome, adding client_order_id, deciding whether a retry is safe, or confirming paper vs live before sending an order.

★ 32
mphinance
mphinance/alpha-skills

write-a-skill

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.

★ 32
mphinance
mphinance/alpha-skills

wireframe-sketch

A hand-drawn wireframe exploration — graph-paper background, marker / pencil tone, multiple tab labels for variants, sticky-note annotations, scribbled chart placeholders, hatched fills. Reads like a designer's whiteboard before any pixels are committed. Use when the brief asks for "wireframe", "sketch wireframe", "hand-drawn", "lo-fi", "whiteboard", "草稿", or "手绘原型".

★ 32
mphinance
mphinance/alpha-skills

weekly-update

Single-file horizontal-swipe slide deck for a weekly team update — shipped, in flight, blocked, metrics, asks. 6–8 slides. Use when the brief mentions "weekly update", "team update slides", "weekly status", "周报演示".

★ 32
mphinance
mphinance/alpha-skills

webull-openapi

Trade stocks, options, futures, crypto, and event contracts on Webull. Query real-time and historical market data. Manage accounts and positions. Supports US, HK, JP, SG, TH, MY, UK, MX, BR, EU, ZA, and AU regions with configurable risk controls.

★ 32
mphinance
mphinance/alpha-skills

web-prototype

General-purpose desktop web prototype. Single self-contained HTML file built by copying the seed `assets/template.html` and pasting section layouts from `references/layouts.md`. Default for any landing / marketing / docs / SaaS page when no more specific skill matches.

★ 32