poc-first

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.

POC-First Skill

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.

---

When to Use

• Unsure how an API responds (IBKR, Alpaca, any third-party)
• Unsure about a library's actual behavior or return format
• Debugging something and can't determine root cause from code alone
• A fix "should work" but you're not confident
• Integrating with a new service or endpoint
• User reports behavior that contradicts your understanding

When NOT to Use

• You've read the source code and the behavior is clear
• You've seen the exact pattern working elsewhere in this codebase
• Pure logic/algorithm work with no external dependencies

---

Process

Step 1: Admit Uncertainty

Say explicitly what you're unsure about. Examples:

• "I'm not sure what format IBKR returns for historical bars"
• "I don't know if this endpoint requires authentication"
• "I'm uncertain whether this library handles timezone conversion"

Never pretend to know. If you're 70% sure or less, POC it.

Step 2: Write a Minimal POC Script

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:

• Minimal - only test the one thing you're uncertain about
• Disposable - write to /tmp/, never into the project
• Observable - print raw outputs, types, structures
• Safe - read-only where possible, use paper mode for trading APIs
• Fast - should run in seconds, not minutes

Step 3: Run It and Read the Output

Run the POC and read the actual output. Do not skip this step.

cd /Users/mattc/Desktop/warrior && python /tmp/poc_test.py

Step 4: Use Real Results to Inform Implementation

Now implement based on what you observed, not what you assumed.

Document what you learned in a brief comment if the behavior was surprising.

---

Examples

Example 1: Unsure About API Response Format

#!/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()

Example 2: Unsure About Library Behavior

#!/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)}")

Example 3: Debugging - Can't Find Root Cause

#!/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())

---

Root Cause Debugging

When debugging an issue:

1. Reproduce first - Can you trigger the bug?
2. Gather evidence - Logs, console errors, network requests, actual API responses
3. Form a hypothesis - Based on evidence, not guesses
4. POC the hypothesis - Write a minimal script that tests your theory
5. Fix based on findings - Only now write the actual fix
6. Verify the fix - Run the POC again or the actual system to confirm

Never apply a fix you can't explain with evidence.

---

Cleanup

After the POC has served its purpose:

rm /tmp/poc_*.py

POCs are disposable. They exist to answer a question, then they're gone.