Repository navigation
v0.2.0 — anti-patterns and guardrails in every prompt
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 atlocalhost: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.