order-book-reconstruction
Skill13 starsChanged 5 days agoApache-2.0View on GitHub
Design, implement, or audit an exchange limit-order-book parser and state reconstructor from ITCH-like market-data messages or normalized MBO/L2 feeds. Use for order lifecycle, sequencing, snapshots, recovery, and book invariants; not for generic data cleaning.
In this repository19 other files it gives its agents.
- agent-based-market-simulationSkill
- code-understandingSkill
- etf-arbitrageSkill
- exchange-gateway-engineeringSkill
- execution-analysisSkill
- hft-market-replaySkill
- interview-simulatorSkill
- lob-microstructureSkill
- low-latency-performanceSkill
- market-makingSkill
- mathematical-reasoningSkill
- pre-trade-risk-controlsSkill
- production-trading-operationsSkill
- quant-research-validationSkill
- queue-position-modelingSkill
- research-paper-tutorSkill
- socratic-tutorSkill
- tick-data-engineeringSkill
- volatility-market-makingSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Validate invariants: Check nonnegative quantities, no zero-sized resting orders, one active order ID at a time where required, aggregate …
- Distinctive: line 17
Cross-check against reference outputs: Use known protocol examples, independent decoders, venue-provided snapshots, and carefully selected …
- Distinctive: line 24
Keep symbol/market-session metadata versioned.
- Distinctive: line 30
Do not reverse-engineer a proprietary feed from examples when an authoritative spec is available.
- Distinctive: line 31
Do not resume a reconstructed book after a sequence gap without a verified recovery point.
- Distinctive: line 32
Do not call an L2 aggregate book an exact FIFO queue.
- Distinctive: line 33
Never convert protocol quantities/prices with undocumented scaling factors.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Order-Book Reconstruction
Act as an exchange-feed and market-data engineer. Reconstruct the exchange-visible book according to the venue's published protocol and matching rules. Never assume that two venues encode the same order lifecycle.
Workflow
- Read the authoritative protocol. Identify message types, field widths, byte order, message framing, sequence-number scope, order-ID scope, price/quantity scale, symbol mapping, session reset rules, and correction/bust semantics. Record the spec version and effective date.
- Choose the state model. For MBO, maintain order-ID state and derive price levels; for MBP/L2, maintain aggregate levels and accept that individual queue rank is unavailable. Represent bid/ask sides with explicit price ordering and integer ticks.
- Specify transitions before coding. Map each message to a state transition: add, partial execution, full execution, cancel, replace, delete, trade-only event, cross/auction event, or session control. Define behavior for unknown IDs and duplicate messages.
- Handle sequence and recovery. Detect gaps, duplicates, out-of-order delivery, retransmissions, and channel resets. Stop publishing a trusted book after a gap until protocol-correct recovery (snapshot/replay or channel recovery) completes. Do not silently skip unknown state-changing messages.
- Make updates atomic. Apply each event as one state transition; preserve event order. Treat replace semantics according to protocol (some replacements lose priority; some do not). Do not assume cancel-plus-add unless the spec says so.
- Validate invariants. Check nonnegative quantities, no zero-sized resting orders, one active order ID at a time where required, aggregate depth matching order-level sums, tick alignment, monotonic sequence within the applicable channel, and no crossed book outside documented market states.
- Cross-check against reference outputs. Use known protocol examples, independent decoders, venue-provided snapshots, and carefully selected event sequences. Build tests for every message type and transitions around boundary values.
- Expose observability. Emit sequence-gap counters, parse errors, unknown-ID events, recovery state, message throughput, book age, and last trusted sequence.
Data structures and correctness notes
- Store prices as integer ticks or fixed-point integers; avoid binary floating-point equality for price keys.
- Preserve exchange event timestamp and local receive timestamp separately. Do not overwrite one with the other.
- Keep symbol/market-session metadata versioned; corporate actions and instrument changes can invalidate historical assumptions.
- Distinguish order messages from trade messages: a trade print does not necessarily tell you how much displayed depth remains unless the feed semantics establish it.
- For L2 snapshots, model depth truncation and aggregated quantity explicitly.
Guardrails
- Do not reverse-engineer a proprietary feed from examples when an authoritative spec is available.
- Do not resume a reconstructed book after a sequence gap without a verified recovery point.
- Do not call an L2 aggregate book an exact FIFO queue.
- Never convert protocol quantities/prices with undocumented scaling factors.
Deliverable
Provide a protocol map, event/state transition table, data model, recovery design, invariant checklist, test matrix, and a reproducible replay comparison. Identify every message type or recovery case not yet handled.
Further reading
- Nasdaq TotalView-ITCH 5.0: https://nasdaqtrader.com/content/technicalsupport/specifications/dataproducts/NQTVITCHspecification.pdf
- Nasdaq OUCH order-entry overview: https://nasdaqtrader.com/Trader.aspx?id=OUCH
- Nasdaq OUCH 5.0 specification: https://www.nasdaqtrader.com/content/technicalsupport/specifications/TradingProducts/OUCH5.0.pdf
- NYSE Pillar platform and specifications: https://www.nyse.com/trade/pillar
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

