SimpleFunctions Research Workflow

When to use

• The user asks to research a topic or thesis ("research Fed cuts", "what do markets say about X")
• An agent needs to understand the current market state on a specific theme before making a recommendation
• A long-running monitor needs a structured research packet on a topic it's tracking

Prerequisites

npm install -g @spfunctions/cli
# Optional: sf login (most read commands work without auth)

The sf investigate and sf query commands work without authentication. sf me and account-scoped reads require sf login.

Instructions

Step 1: Start with a research router

sf investigate is the read-only research router. It calls public world, query, econ, gov, traditional-market, and tool-planning surfaces in parallel, tolerates partial failures, and returns evidence + next commands in one envelope.

sf investigate "<topic>" --json --limit 5

Example:

sf investigate "Fed rate cuts CPI" --json --limit 5

This returns:

• normalized Kalshi markets matching the topic
• normalized Polymarket markets
• implied probabilities
• traditional-market anchors (SPY, VIXY, TLT, GLD)
• FRED economic series (CPI, UNRATE, FEDFUNDS)
• source context (recent news)
• next commands to drill deeper

If the topic is broad or the user wants a different angle, also run:

sf query "<refined question>" --json --limit 3

sf query is natural-language market search. Use it when you have a specific question, not a topic keyword.

Step 2: Inspect the top candidate markets

For each top-3 market from Step 1, call:

sf inspect <ticker> --json

Returns:

• market metadata (title, venue, deadline, description)
• prices (bestBid, bestAsk, last, spread)
• liquidity (volume, open interest)
• indicators (iy, cri, las, vr, residualVr, regime score)
• regime state (label, confidence, fresh)
• related surfaces (cross-venue counterpart, siblings, contagion)
• follow-up actions

Step 3: Pull world context

If the topic is macro or geopolitical, pull the world snapshot for the salience context:

sf world --json
# or for a specific topic
sf world --topic <topic-slug> --json

This shows what SF's salience ranker considers most material right now — divergences, residual volume signals, consensus breaks, resolving-soon markets.

Step 4: Synthesize

Produce a 4-section research packet:

1. Market state What do the markets say about this topic? Cite the top-3 prices and what they imply.

2. Anchors What traditional markets / econ data corroborate or contradict the prediction-market read? (e.g., "WTI at $100 is consistent with the Iran-risk market at 45¢")

3. Catalysts What upcoming events would resolve or move the market? Pull from sf investigate output's catalyst field.

4. Next actions Concrete next commands: sf inspect <ticker> for a specific market, sf watchlist add to track, sf create to build a thesis.

Optional Step 5: Build a thesis from the research

If the user wants to turn the research into a position:

sf create "<thesis statement based on research>"

See the sf-thesis-build skill for the full thesis lifecycle.

Expected output shape

Each --json command returns an envelope:

{
  "status": "ok" | "partial" | "error",
  "data": { ... },
  "warnings": [],
  "nextActions": [ { "description": "...", "command": "..." } ]
}

Always check status before assuming data is complete.

Errors and recovery

• `MissingApiKeyError` on world.read: world.read is cost-bearing. Set SF_API_KEY via sf login, or use the public GET /api/agent/world endpoint (free).
• Partial results in `investigate`: one upstream may have failed; check warnings array. Other data is still usable.
• No matching markets: try sf scan --keyword "<topic>" --json for broader search.

Related skills

• sf-discover — find quality-ranked opportunities (not topic-specific research)
• sf-inspect — deep dossier on one ticker
• sf-thesis-build — turn research into a structured causal tree

Reference docs

• <https://docs.simplefunctions.dev/cli/agentic-cli>
• <https://docs.simplefunctions.dev/build/headless-agent>
• <https://docs.simplefunctions.dev/integrations/common-workflows>