// When uncertain about API behavior, library usage, or integration details, build a minimal proof-of-concept against live APIs before implementing. Prevents hallucinated solutions.
| name | poc-first |
| description | When uncertain about API behavior, library usage, or integration details, build a minimal proof-of-concept against live APIs before implementing. Prevents hallucinated solutions. |
When you are uncertain about how something works, prove it first with a minimal throwaway script against live APIs. Do NOT guess, assume, or hallucinate behavior.
Say explicitly what you're unsure about. Examples:
Never pretend to know. If you're 70% sure or less, POC it.
Create a throwaway script in /tmp/poc_*.py (or .js, .sh, etc.):
#!/usr/bin/env python3
"""POC: [what we're testing]"""
# Minimal imports - only what's needed
# Hit the real API / use the real library
# Print raw results so we can see actual behavior
if __name__ == "__main__":
result = the_thing_were_unsure_about()
print(f"Type: {type(result)}")
print(f"Value: {result}")
# Print structure if complex
if hasattr(result, '__dict__'):
print(f"Attrs: {vars(result)}")
Rules for the POC:
/tmp/, never into the projectRun the POC and read the actual output. Do not skip this step.
cd /Users/mattc/Desktop/warrior && python /tmp/poc_test.py
Now implement based on what you observed, not what you assumed.
Document what you learned in a brief comment if the behavior was surprising.
#!/usr/bin/env python3
"""POC: What does IBKR return for reqMktData snapshot?"""
from ib_insync import IB, Stock
ib = IB()
ib.connect('127.0.0.1', 7497, clientId=99)
contract = Stock('AAPL', 'SMART', 'USD')
ticker = ib.reqMktData(contract, snapshot=True)
ib.sleep(2)
print(f"last: {ticker.last}")
print(f"bid: {ticker.bid}")
print(f"ask: {ticker.ask}")
print(f"volume: {ticker.volume}")
print(f"full ticker: {ticker}")
ib.disconnect()
#!/usr/bin/env python3
"""POC: Does pandas resample include the right edge?"""
import pandas as pd
idx = pd.date_range('2024-01-01 09:30', periods=10, freq='1min')
df = pd.DataFrame({'close': range(10)}, index=idx)
resampled = df.resample('5min').last()
print(resampled)
print(f"Index values: {list(resampled.index)}")
#!/usr/bin/env python3
"""POC: Is the WebSocket actually sending messages?"""
import asyncio
import websockets
async def test():
async with websockets.connect('ws://localhost:8000/ws/scanner') as ws:
for i in range(5):
msg = await asyncio.wait_for(ws.recv(), timeout=5)
print(f"Message {i}: {msg[:200]}")
asyncio.run(test())
When debugging an issue:
Never apply a fix you can't explain with evidence.
After the POC has served its purpose:
rm /tmp/poc_*.py
POCs are disposable. They exist to answer a question, then they're gone.
Debug the trading webapp frontend using Chrome DevTools MCP. Use when frontend is not behaving as expected, WebSocket connections failing, charts not rendering, or API calls returning errors.
Check PRD progress and determine next steps for the Warrior trading system. Use when user asks "what's next", wants project status, or starting a new session.
Reviews trading code for safety invariants and code reuse. Use when modifying trading logic, orders, positions, sizing, or adding features that interact with IBKR.