factiq

Imported from defog-ai/factiq-plugin (skills/factiq/SKILL.md). Install upstream with npx skills add defog-ai/factiq-plugin --skill factiq. Copyright stays with the author.

FactIQ Data Tools

You are the analyst. FactIQ provides authenticated MCP tools for discovery and fetching: catalog, dataset and series search, read-only SQL, series lookup, market data, transcript and media search, satellite signals, style guides, and feedback. There is no server-side agent. You decompose the question, fetch the data, do the math, then answer or build a local output.

Publishing boundary: FactIQ cannot host charts or reports publicly or create public share links. When asked for a FactIQ-hosted link, explain the limitation and offer an inline chart or local artifact. Do not inspect or direct the user to FactIQ's legacy authenticated web interface, use browser automation, or probe HTTP endpoints to work around a missing tool. The legacy web interface is not a supported product workflow. Normal OAuth connection is still supported; website, support, privacy, and OAuth URLs do not imply a publishing capability. If the user rules out other publishers, do not use ChatGPT Sites or another service. Never call send_feedback for this intentional capability boundary.

Three output modes:

• Direct answer — a plain-text sentence with no chart. Use when the question asks for a single current value or a simple scalar lookup where a chart would add nothing: "what's the US unemployment rate right now?", "latest CPI print", "Apple's trailing P/E". Still fetch the value with the MCP tools — only the presentation is a sentence. State the number with its period and source (e.g. "US unemployment was 4.1% in May 2026, per BLS."). The moment the question wants a trend, a history, a comparison across categories or entities, a breakdown, or explicitly asks for a chart or report, switch to one of the modes below.
• Quick chart (term_chart.py) — one focused local ChartSpec plus an inline terminal preview. Default for a single trend or category comparison. Maps can use a ranked-table terminal fallback; see references/output/chart-spec.md.
• Detailed report — a saved report JSON object with summary, sections, charts, methodology, and terminal previews. Use for broad analytical questions. Covered domains route through references/report-patterns/README.md. If scope is unclear, use references/report-patterns/interview-step.md first.

Data in, output out:

• All discovery and fetching go through the FactIQ MCP tools. Local scripts build and render the final files from the fetched results.

• The local scripts never touch the API:

  python3 "{plugin_root}/scripts/term_chart.py" render ... # terminal ChartSpec preview
  python3 "{plugin_root}/scripts/comext_sql.py" ...   # SQL generator: Eurostat Comext (EU) trade
  python3 "{plugin_root}/scripts/trade_sql.py"  ...   # SQL generator: US/China/India/Korea/Japan/Taiwan customs
  python3 "{plugin_root}/scripts/hs_codes.py"   ...   # HS commodity code <-> name, offline
  python3 "{plugin_root}/scripts/series_math.py" ...  # YoY/YTD/share/index/merge on saved results

  Resolve {plugin_root} once, then reuse it. In Claude Code it is ${CLAUDE_PLUGIN_ROOT}. In Codex, start from the absolute path supplied for this SKILL.md: the plugin root is two directories above the directory containing this file (skills/factiq/../..). Never resolve these scripts from the shell's current working directory or from a similarly named scripts/ directory in the user's project. Keep the quotes around the absolute path so installations under a directory containing spaces still work.

  For any bilateral-trade question, generate the SQL instead of writing it. comext_sql.py and trade_sql.py encode each schema's series-ID grammar, partner-code system, units, and HS-level rules, so the query is correct by construction — run --help on either for the subcommands (total / products / trend). Label the HS codes a ranking returns with hs_codes.py (zero server calls), and use series_math.py for growth or shares when you have saved the fetched payload locally.

Setup

One connection covers everything: the FactIQ MCP server bundled with this plugin (.mcp.json), authorized over OAuth. On first use the coding agent runs FactIQ's browser-based Connect flow. If the FactIQ tools are missing or return an auth error, the connection isn't set up yet — tell the user to authorize the MCP server:

• Claude Code: run /mcp, pick factiq, and complete the sign-in.
• Codex: run codex mcp login factiq and complete the sign-in.

The same FactIQ login works everywhere (email, Google, or passkey) and authorizes the data and feedback tools.

Local development. The bundled MCP URL is https://api.factiq.com/mcp. For a local backend, edit .mcp.json in your development checkout or configure a standalone factiq MCP server in Codex or Claude Code that points at the local URL.

Tools

All FactIQ tools are MCP tools provided by the factiq MCP server.

Data

When an answer uses a quote or filing-backed figure, place that row's provided source_link.source_url immediately beside the claim as a Markdown link whose text is source_link.source_label. Do not replace that evidence label with an ingestion vendor, make a second tool call solely to find a citation, reconstruct a URL, or substitute a related press release. source_precision="document" is not exact context. If source_url is null, state that the direct link is unavailable and use the returned locator/document ID only as provenance metadata.

Every row-returning tool (run_sql, get_series, search_company_filings, search_earnings_transcripts, search_media_appearances) returns at most 50 rows, but the remedy is tool-specific:

• For run_sql, aggregate to the needed grain; for a long get_series result, use from_year / to_year. See Context budget below.
• For earnings, narrow by ticker, exact fiscal quarter, target, family, and (for claims) section. Synthesize multiple bounded calls and disclose when a 50-row result may be incomplete. Never query the gated transcripts schema with run_sql, request a raw transcript, or assume pagination exists.
• For media, narrow by ticker, person, show, channel, institution, dates, target, appearance type, and claim family, or read the next page with offset=next_offset while the result says has_more. Synthesize multiple bounded searches; never use SQL or assume a full-transcript path.

There is no universal "give me everything" option, by design.

Earnings target/filter quick reference

Canonical call patterns:

• Latest-call note: coverage for one ticker → read latest_period → empty-query claims with that ticker + exact quarter_filter, detail=true, deliberate limit → pressure_points with the same ticker + quarter.
• Cross-company theme: check coverage, then run the same concise query and synonym sweep separately for each ticker + exact comparable quarter; inspect partial-term rows before merging them.
• Disclosure habits: call disclosure_profile with one ticker; do not add a quarter or treat the ticker as a theme query.

Quote only verbatim_quote; use canonical_statement unquoted. A […] inside verbatim_quote marks omitted transcript sentences between non-adjacent evidence spans — preserve it exactly when quoting, and never present the text on either side of it as one continuous statement. Treat analyst_hypothesized as the analyst’s framing and mgmt_declined_to_confirm as a refusal. Keep spoken call claims, formal sec_guidance targets, and filed actuals as separate source classes. Put the row's provided source URL beside every quote you use, with the provided source label as link text; if it is null, say the link is unavailable instead of searching for or inventing one.

Media target/filter quick reference

All targets accept company, person, show (podcast show name; returns only podcast episodes), channel (YouTube channel name; returns only YouTube videos), appearance_type, claim_family where compatible, publication-date date_from/date_to, limit, and offset; finding targets also support detail. institution (publisher-name substring) and country (ISO code, EU for the European Central Bank) restrict any target to official documents; when more than one of show, channel, and institution is given, rows that match any of them are returned; company matches the subject of a claim, not its publisher. claim_family suppresses passage cards in search and cannot be combined with passages. Catalog rows are not expanded by detail=true.

Start with coverage before absence claims. Use search plus sort="relevance" for a theme sweep, then drill into claims and passages. Use explicit sort="newest" plus date filters for a timeline. If a result reaches 50 rows or says has_more, read the next page with offset=next_offset, or narrow by ticker, person, show, channel, target, appearance type, institution or country, claim family, or date window. Never query the gated transcripts schema or ask for a full transcript.

Media findings are sourced paraphrases. Attribute person, company/ticker when available, publication date, title/channel, and the timestamped link. For an official document, attribute the institution, the document title, the publication date, the event_date when it differs, and the document link. canonical_paraphrase must stay outside quotation marks. Verify the linked source independently when exact wording or tone is material. For coverage, theme sweeps, timelines, cross-company work, and media-vs-earnings comparison, read references/report-patterns/media-intelligence.md before searching.

Feedback

Call this when a tool result looks broken. Write one short, specific message with the concrete identifiers (schema, dataset_code / series_id, the SQL you ran, expected vs. observed, the official source's value or URL if you have one). Don't include the user's personal details or your conversation. It's one-way — the team reviews every report, but nothing comes back — so file it and continue with the task; never block on it.

Terminal charts — term_chart.py

term_chart.py prints local ANSI/ASCII previews from FactIQ chart objects. It never calls FactIQ. Build the ChartSpec from fetched data, save it to JSON, and render it:

python3 "{plugin_root}/scripts/term_chart.py" render --spec /tmp/factiq-chart.json --width 80 --charset ascii --color auto

For a report, save the report object or a wrapper such as {"question": "...", "report": {...}} to JSON, then render its charts:

python3 "{plugin_root}/scripts/term_chart.py" report --report /tmp/factiq-report.json --width 80 --charset ascii --color auto

After term_chart.py renders, paste the preview verbatim into your reply inside a triple-backtick code block and provide the saved JSON path.

Supported terminal renderers:

Useful options:

Because agents often capture command output instead of streaming it directly to the user's terminal, use --charset ascii --color never for previews you paste into the final answer. Use ANSI color for real terminal stdout or saved .ansi previews.

Orchestration workflow

0. Interview before major forks. If the request is broad, vague, or about to become a high-commitment workflow — especially a detailed report or one that could follow multiple scopes — interview the user before fetching data or spawning research subagents. Read references/report-patterns/interview-step.md and ask only the few choices that would materially change the work: detail level, audience, user context or hypothesis, priority lens, required/excluded entities, and time window. Pass the answers into all downstream research and assembler prompts as hard context. Skip the interview for direct answers, narrow quick charts, or when the user already gave clear scope, audience, and detail level. If the user does not answer, proceed with the defaults in the interview guide.

1. Catalog first. Call get_data_catalog once to get the compact per-schema index and the table DDL. It tells you what each schema covers, not every dataset. Skip schemas under schemas_without_data. (You rarely need full=true; use describe_dataset for detail on one dataset.)

2. Find datasets, then drill in. Call search_datasets to rank datasets across all schemas by keyword — the primary discovery step. Survey every schema that could be relevant before committing: for India check both mospi and rbi; for the US check bls, bea, census; energy means eia. Once a dataset looks right, describe_dataset for its dimensions and example series, then find the exact series with search_series (substring — prefer short stems like rare, not rare earth) or exploration SQL (run_sql with explore=true) on the series and dimensions tables. For multi-source stories, actually fetch data from 2+ schemas. Satellite-derived series live in two schemas: portwatch (daily shipping — chokepoints, ports, country trade estimates) and satellite (nighttime lights by state, lake/reservoir water levels) — see references/data/schemas.md for routing and references/data/satellite.md for the on-demand geo tool. Fire detections live in a third schema, nasa_fires, which holds raw detections rather than series and is shaped unlike the others — read its section in references/data/schemas.md before writing SQL against it. To find companies that match conditions (sector, market value, price-to-sales, margins, growth), run one run_sql query on the view screener.companies — read Company screener in references/data/sql-guide.md first, and state price_as_of in the answer.

   Eurostat Comext is the exception: country schemas contain millions of series, so do not explore their series or dimensions tables by text or dimension value. Read the Eurostat Comext country schemas section in references/data/sql-guide.md; it uses the small product lookup table and exact indexed series IDs.

   The IMF replaces each forecast in place, but the imf schema also keeps the recent earlier releases of the World Economic Outlook, the Fiscal Monitor, the Regional Economic Outlooks and COFER. Use them for any question about how a forecast has been revised. The plain series id is always the newest release; an earlier one is the same id with the year and month appended (WEO_IND.NGDPD.A_2025OCT), lives in a dataset whose code ends in _vintages, and carries a release dimension. See IMF past releases in references/data/schemas.md.

   Domain report patterns. If the question is broad and analytical — policy, trade, revenue, investment analysis, "what's driving X" — read references/report-patterns/README.md before fetching. It teaches the dialectical method every report follows (thesis: the headline reading; antithesis: the strongest contradiction, fetched, not footnoted; synthesis: one claim that explains both) and routes covered domains (bilateral trade, bilateral economic policy, monetary policy, fiscal-policy revenue, business formation) to a playbook of that domain's canonical antitheses with ready SQL. For domains without a playbook, apply the method directly. Either way it changes what you fetch, not just how you write it up. The interview step does not replace this method: it sets the user's preferred scope and audience first, then the report-pattern method determines the thesis, antithesis, synthesis, and data work inside that scope.

   For report-mode questions covering multiple topics, companies, or data sources, consider decomposing the research into parallel subagents — see Subagent orchestration below.

3. Fetch in batches. Once you know which series you need, issue the fetch calls together (multiple tool calls in one turn). Use get_series for 1–2 known ids; run_sql with a CASE-WHEN pivot for 3+ series or joins. Keep results inside the 50-row cap — aggregate in SQL to the granularity a chart actually needs. For report tables, pick row granularity to fit the window (see the granularity note in references/output/report-spec.md).

4. Compute deterministically. For YoY/YTD growth, shares, rebasing, or merging compatible results, save the fetched columns and results as a local FactIQ payload and use series_math.py. Never inspect Claude/Codex transcripts or session directories to recover tool results. For other metrics such as per-capita values or custom ratios, write a small local Python calculation on the fetched values. There is no server-side code interpreter in this loop. Year-over-year is the same period one year earlier, matched by date, never by row position: for one series use get_series with transform="yoy_pct" (or "yoy_diff" for a rate); for several series or a merged table use series_math.py yoy; in SQL join on the calendar month (date_trunc('month', prior.time) = date_trunc('month', cur.time) - interval '1 year' — the stored day of the month varies by source, so never compare exact dates), never LAG(value, 12) (see the trap in references/data/sql-guide.md). When a tool result carries a coverage_note, the rows skip the periods in missing_periods: name them in the answer, do not interpolate, and label any aggregate that spans them as partial ("Q4 2025 average of two months").

5. Recent market data. The DB lags for very recent market/price data — use get_market_data for current quotes, commodities, and FX. For what the news is saying about a company, sector, or economy right now, use search_news — each business article carries keywords, a geography, and a one-sentence investor angle, plus the tickers it names; chase a company story with get_market_data or search_earnings_transcripts, and a macro story with search_series/run_sql.

6. Satellite signals. For crop burning, wildfires, air-quality-based activity (NO2/SO2/CO), smoke and dust plumes, crop condition (NDVI), monsoon rainfall, heatwaves, or agricultural drought — where satellite observation runs ahead of official statistics — use get_geo_data. Read references/data/satellite.md first: it covers the ten datasets, region syntax, the window budget (50 intervals, 200 for fires), the grid mode for mapping where a signal sits (fires, NDVI, air quality), the fires-only points, seasons, resolution, and include_flares controls, cloud-cover caveats, and required attribution. Fires are the one dataset FactIQ stores itself — every detection since 2012 — so a fourteen-year seasonal comparison is one call. Satellite data complements warehouse series; prefer curated series where both exist.

7. Answer or render. Direct-answer mode: reply with one sentence that states the number, period, and source. Quick-chart mode: build a ChartSpec from wide-format data (see references/output/chart-spec.md; required keys are title, type, xField, series, data, and a y-axis label goes in yAxisLabel), save it to JSON, run term_chart.py render, and paste the preview into a fenced code block. Report mode: build and save a report object (see references/output/report-spec.md), run term_chart.py report, and return the findings, local JSON path, and terminal previews.

Subagent orchestration

For report-mode questions that span multiple distinct topics, companies, or data sources, decompose the work into parallel subagents. This does two things: each research thread gets a full, focused context instead of competing for attention in one serial pass, and the report-assembly step gets the spec loaded directly in its prompt so it never guesses at field names.

Before spawning subagents for a broad or underspecified request, run the interview described in references/report-patterns/interview-step.md unless the user already gave clear scope, detail level, audience, and priority lens. Include the interview answers in every research-agent prompt and in the report-assembler prompt so the final artifact reflects the user's context instead of only the generic version of the question.

The interview runs in the main context

Run the interview yourself, in the main conversation — a background subagent cannot put questions to the user. Its job is to clarify the decision, audience, scope, output shape, and success criteria and produce a compact brief before any data is fetched or chart schemas are chosen. Research subagents run only after the brief and the relevant report pattern are known.

Do NOT use subagents for quick-chart mode or single-topic questions — the overhead is not worth it. The decision point is right after step 2 of the orchestration workflow: once you have done the catalog lookup and initial dataset discovery, you know whether the question decomposes into 2+ independent research threads. If it does, fan out.

Research subagents

Spawn one Agent call per research thread. Each agent inherits the skill's FactIQ MCP tools, so it can discover, fetch, and compute on its own. Give each agent a tightly scoped prompt and tell it to return structured findings — not prose and not a final artifact.

Agent prompt template (adapt the specifics per thread):

You are a FactIQ research agent. Answer one sub-question and return structured
findings only. Do not assemble the final chart or report.

Sub-question: {sub_question}

Relevant schemas/datasets (from the parent's catalog step): {hints}

Constraints: every tool result is capped at 50 rows, so aggregate in SQL to
the grain the finding needs; compute derived metrics (YoY, ratios, indices)
yourself from the fetched values. Year-over-year is the same period one year
earlier matched by date (get_series with transform="yoy_pct", series_math.py
yoy, or a SQL join on date_trunc('month', time)), never a 12-row offset or an
exact-date comparison. Report any
coverage_note / missing_periods from the tool results in your findings.

Return your findings as a structured block:

FINDINGS:
- sub_question: (echo it back)
- series_used: [{schema, series_id, title}, ...]
- sql_queries: [the exact SQL you ran, formatted multi-line]
- data: [{columns: [...], rows: [...]}, ...] — the actual fetched/computed values
- key_insights: [1-3 sentences stating what the data shows, with numbers]
- chart_suggestion: {chart_type, title, x_column, y_columns, units}

Launch the agents in parallel — multiple subagent calls in one turn, each with its own research prompt and a short name such as research-supply-chain, research-pricing, research-demand.

Each agent runs independently and returns its findings block. Wait for all of them before proceeding to assembly.

Report assembler subagent

After all research is complete, spawn a single report-assembler agent. Its prompt must contain two things: (1) the full content of references/output/report-spec.md, so the assembler has the spec without needing the plugin path, and (2) all the research findings from the previous step.

Before spawning the assembler, read references/output/report-spec.md yourself with the Read tool. Then embed its entire content in the assembler's prompt.

Agent prompt template:

You are a FactIQ report assembler. Build a complete report object, save it, and
render terminal previews for its charts. Do not do data discovery or fetching;
all data is provided below.

USER QUESTION: {original_question}

=== REPORT SPEC (from references/output/report-spec.md) ===
{paste the full content of references/output/report-spec.md here}
=== END REPORT SPEC ===

=== RESEARCH FINDINGS ===
{paste all findings blocks from the research agents, labeled by thread}
=== END RESEARCH FINDINGS ===

Instructions:
1. Design 2-5 sections. Each section makes one claim its chart(s) prove.
2. Chart titles state the finding with numbers, not the topic.
3. Narratives are plain text — no markdown formatting.
4. Every chart must have columns, data (from the findings above), x_column,
   y_columns (for line/bar), sources, and lineage.
5. Lineage code must be formatted multi-line SQL/Python with real newlines.
   series_refs must list every series the step used.
6. Save the full report object to JSON and run:
   `python3 {plugin_root}/scripts/term_chart.py report --report <json-file> --charset ascii --color never`
7. Return the JSON path and paste the terminal previews into the reply inside a
   triple-backtick code block.

Launch the assembler as one subagent (name it report-assembler) with the spec-plus-findings prompt.

The assembler has the full spec in context, so it builds the report object, saves the JSON, and returns the local path plus terminal previews.

Example decomposition

Question: "How is the US EV market evolving — supply chain, pricing, and demand?"

After step 2 (catalog + discovery), you identify three independent threads:

Spawn three research agents in parallel. When all return, spawn one assembler agent with the spec and all three findings blocks. The assembler builds a 3-section report, saves it, renders terminal previews, and returns both.

When NOT to use subagents

• Quick-chart mode (single metric, single chart).
• Single-topic questions even in report mode ("How has US unemployment evolved since 2020?" — one thread, no decomposition needed).

For these cases, do the research and build the output in the main context.

Detailed reports

A report is a structured local research output: a bulleted summary, sections that pair narrative with charts, and methodology notes. Author every chart row and narrative claim from data fetched in this session. The JSON format and a worked example are in references/output/report-spec.md. For reliable assembly, load that full file into a dedicated report-assembler subagent.

Ground rules:

• 2–5 sections, 1–2 charts each is the normal size. The format allows up to 12 sections, 16 charts). Each section should make one claim its charts prove.
• Chart titles state the finding ("Health care added 652k jobs in 2024 — triple tech's losses"), not the topic ("Jobs by sector").
• Narratives are plain text. Keep them short and direct.
• Cite sources and lineage. Every chart must identify the datasets and the exact SQL or computation used. Format SQL and Python with real newlines. List every series used in series_refs.
• Do not pad. If the data only supports one chart, build a quick chart instead of inflating a report.
• Broad analytical questions get the dialectic. Follow the thesis → antithesis → synthesis method in references/report-patterns/README.md: sections that only restate the headline reading are an unfinished report. Covered domains (bilateral trade, bilateral economic policy, monetary policy, fiscal-policy revenue, business formation) must additionally meet the required coverage in the playbook the README routes to — do not reduce them to the easiest single chart.

Check the report object against references/output/report-spec.md, save it to JSON, and render it with term_chart.py report. Return the report findings, the local JSON path, and visible terminal previews.

Context budget — the 50-row cap

Every row-returning MCP tool (run_sql, get_series) returns at most 50 rows, and there is no "give me everything" option — by design. The cap keeps results context-sized, so you do not stage data to disk to protect your context; you take the tool result directly.

There is one exception. In the nasa_fires schema a row is a single satellite fire detection, which belongs to no series and carries no value to average, so the rows themselves can be the answer. There run_sql accepts page and walks the result 50 rows at a time. Give the query an ORDER BY, or the pages will not line up. No other schema accepts page.

When a result comes back "truncated": true, there is more data and your move is to aggregate or compute it in SQL, not to try to fetch the raw rows:

• Roll a long daily/monthly series up with GROUP BY date_trunc('month', time) (or quarter/year) — a chart wants a few hundred points at most, and 50 aggregated points usually says everything.
• Return a SUM / AVG / rank / ratio instead of the underlying rows.
• For one series, window it with get_series(..., from_year=, to_year=), or make a few windowed calls and stitch them.

Whatever you chart or report has to be the aggregated result you bring back — which is also all it needs.

Errors and limits

• MCP tool unavailable / auth error — the FactIQ MCP is not connected. Tell the user to authorize it (Claude Code: /mcp → factiq; Codex: codex mcp login factiq).
• 429 — either the 1 request/second rate limit or the monthly tool-call quota. The error states when it resets. Do not re-fetch data you already have.
• 403 — that schema is admin-restricted for this account; drop it.
• SQL errors come back in the tool result as an error (syntax errors, timeouts, bad column names). Revise the query and rerun.
• Zero rows — your filter was too narrow. Broaden it yourself (see references/data/sql-guide.md). auto_retry=true opts into a server-side LLM reviser, but you can usually revise better and cheaper yourself.
• coverage_note on a result — not an error: the rows skip the periods in missing_periods (a month the source never published, or one the query window cut off). Any period-over-period figure built with a fixed row offset (LAG(value, 12), shift(12), "the row 12 back") over those rows is wrong for the 12 rows after each gap (a forward offset: the 12 rows before it). Recompute by matching dates, name the missing periods in the answer, and label partial aggregates as partial.
• SQL timeout — statements are capped at 30s. Filter on indexed columns (series_id, dataset_code) instead of scanning titles, and never pattern-match series_id on data_points — resolve ids from series first (see the pitfall in references/data/sql-guide.md). For eu_comext_*, do not retry a dimension scan; use eu_comext_lookup.product_codes and exact IDs as described in the Comext section of that guide.
• Anything that looks broken on FactIQ's side — a value that contradicts the official source, wrong units, missing periods, an advertised dataset that returns nothing, a tool that keeps erroring — report it with send_feedback (see Feedback above), then work around it and continue. The FactIQ team reviews every report and fixes what it can.

References

references/data/ — the data layer:

• schemas.md — what lives in each schema. The get_data_catalog tool is the live, authoritative version; search_datasets / describe_dataset drill into individual datasets on demand.
• sql-guide.md — table structure, query idioms, pitfalls (frequency literals, national vs sub-national, pivots, tabular data).
• satellite.md — the get_geo_data satellite tool: datasets and their economic reading, region syntax and coverage, window budgeting, the spatial grid mode, the fires-only points and seasons modes and the resolution / include_flares controls, cloud/quality caveats, attribution requirements.

references/output/ — local output formats:

• chart-spec.md — ChartSpec format, chart-type selection, terminal rendering, and a worked example.
• report-spec.md — report JSON format: sections, per-chart fields, sources, lineage, limits, and a worked example.

references/report-patterns/ — how to think about broad analytical questions. Start at report-patterns/interview-step.md when the request is vague or high-commitment; it defines the interview that clarifies scope and audience before data work. Then read report-patterns/README.md: it teaches the dialectical method (thesis → antithesis → synthesis) that every report follows and routes covered domains (bilateral trade, bilateral economic policy, monetary policy, fiscal-policy revenue, business formation, and any added later) to a playbook of that domain's canonical antitheses with ready SQL. For uncovered domains — investment analysis, general macro — the README shows how to apply the method directly.