Skip to content

v0.2.0 — anti-patterns and guardrails in every prompt

Choose a tag to compare

@shing1211 shing1211 released this 28 Sep 15:19
· 71 commits to main since this release

v0.2.0 — the judgement sections

Every one of the 38 prompts now carries the two sections README.md and
CONTRIBUTING.md present as what makes a prompt worth reading over a wall of
prose:

  • Anti-Patterns (Never Do These)
  • Guardrails

No new prompts in this release, and no existing guidance removed. This adds
the part that was missing.

What was actually missing

Measurement before the work, not after:

Count
Had both sections 17
Had one 14
Had neither 7

The 7 with neither included every broker SDK prompt — the files a reader is
most likely to trust on name alone.

What the sections say

The anti-patterns name failures a given prompt's subject can actually
produce, not generic advice. Examples:

  • IBKR — treating Client Portal as a remote hosted API when it is a local
    bridge at localhost:5000; assuming live and paper are separable when the
    API mirrors whichever account TWS holds; retrying a timed-out order
    request, converting an unknown order state into a duplicate.
  • Futu — inferring binary frame layouts from observed traffic, which
    breaks silently on upgrade and corrupts orders rather than reads; reusing a
    request serial after reconnect, matching a stale response to a new request.
  • trading-risk — hard-coding a maintenance margin threshold that is
    actually a per-broker, per-account-type mandate.
  • event-driven — publishing before the transaction commits; treating
    at-least-once as exactly-once; a side effect in a consumer with no
    idempotency key.

The guardrails are written as checks that can fail:

  • trip the kill switch in a test and assert no order reaches the broker
  • inject a timeout after submission and assert reconciliation, not a retry
  • prove redaction with a test that scans everything the suite emits
  • inject gaps and duplicates and assert resnapshot, not a plausible book
  • measure trade-direction accuracy against a labelled sample, because VPIN
    inherits that error

Shared gates, stated once

All seven broker prompts independently restated the same items — quality
gates, fuzz, redaction, the compatibility matrix, the live-trading gate,
bounded allocation, order reconciliation. Seven restatements drift seven
ways, so the ten venue-independent gates now live once in sdk-build.md
under Cross-Cutting Guardrails. Each broker prompt keeps the gates that
are genuinely its own.

Two gates are not in any broker prompt and are new:

  • bound allocation before the allocation happens, not after reading a
    length field
  • prove redaction with a test, because redaction asserted in prose is not
    redaction

CI now enforces all three

Check Catches
check_nav.py a prompt that renders but is missing from the sidebar
check_vendor_claims.py vendor internals asserted as fact; risk thresholds stated as rules
check_prompt_sections.py a prompt shipping without either section

Every check is proven to fail by injection, not merely to pass. Five of the
defects found in the checks themselves were found this way — including one
that passed when it should have failed, and a discharge window that let one
config entry's framing excuse a neighbour's hard-coded value.

The section check is structural only. A prompt can pass it and still be
filler, and the script says so in its own docstring. What it prevents is the
next prompt shipping without the sections, which is how the gap opened.

Also in this release

The 0.1.1 corrections are included, and the 0.1.1 changelog section
remains the reference for the four wrong vendor facts. If you built an
adapter from v0.1.0, read it before trusting any of the values.

License

MIT.