Query Fan-Out Analysis

Objective

Turn one seed keyword or prompt into a transparent, multi-provider map of the queries an AI search workflow may use to resolve the request. Compare recurring themes across independent runs and platforms without claiming access to hidden reasoning or a fixed consumer-product query list.

Non-negotiable boundaries

• Treat query fan-out as probabilistic and context-dependent. The same input may produce different queries across runs, models, accounts, locations, and product surfaces.
• Label a query observed_tool_query only when an API or authorized tool trace explicitly returns the exact executed query string. Preserve that string verbatim.
• If an observed value is empty, non-text, longer than 2,000 characters, or contains an environment credential or credential-shaped secret, drop the entire value and add the collector warning OBSERVED_QUERY_DROPPED_INVALID or OBSERVED_QUERY_DROPPED_SECRET; carry that event into the final failures or limitations. Never rewrite or redact it and still call it observed. The verbatim guarantee applies to retained observed strings.
• Label text generated by the named provider for this analysis synthetic_provider_query. Label a platform-style simulation produced without calling that provider heuristic_simulation.
• Never infer an observed query from an answer, citation, source URL, related question, search-result snippet, thought summary, or query-count field.
• Never claim that an API call reproduces chatgpt.com, the Gemini app, Google AI Mode, claude.ai, or perplexity.ai consumer behavior.
• Never claim access to hidden chain-of-thought, proprietary retrieval logic, or a stable platform-wide fan-out list.
• Keep grounding/search queries distinct from synthetic fan-out candidates. They may overlap, but they are not interchangeable concepts.
• Do not interpret run recurrence as search volume, popularity, or the probability that a consumer product will issue a query.
• Do not claim that covering or ranking for the returned queries guarantees an AI citation.
• Do not force irrelevant comparison, commercial, recency, platform, or best queries merely to fill a quota.
• Never ask the user to paste an API key into chat. Read credentials only from environment variables; never save, echo, log, commit, or include them in a report.
• Prefer a documented provider API over host-model simulation whenever the requested or default model has a supported API route and its environment credential is available. Treat invocation of this skill as authorization for the ordinary default API plan; show the safe plan, but do not pause for a separate cost confirmation.
• Respect an explicit request for simulated-only, offline, no-network, or no-paid-API execution. Do not expand beyond the requested or default providers, models, or run count without authorization.
• Do not persist complete raw API responses unless the user explicitly requests it. Default all report provenance flags to false for raw-response and key persistence.

Read references/simulation-and-evidence.md before assigning provenance or making platform claims.

Intake

Require one seed_input: either a target keyword or a complete prompt.

Accept these optional inputs:

• target language;
• target country, region, locale, or approximate location;
• audience or persona;
• brand, product, business, or topic context;
• time range or freshness requirement;
• desired answer type;
• URL or pasted page content;
• providers, model IDs, run count, or query-count target;
• API-backed, observed-only, simulated-only, or hybrid mode.

Detect the dominant input language when it is clear. Preserve an explicitly requested language. When no locale is supplied, set it to unspecified; do not silently assume the United States. Ask a follow-up only when unresolved ambiguity would materially change the fan-out. Otherwise continue with explicit assumptions.

Preserve observed queries in their returned language. If providers return different languages, retain each original query and add a translation only for comparison. Never replace the original.

Default execution plan

Use these defaults unless the user overrides them:

• Providers: OpenAI/ChatGPT-style API, Gemini API, Google AI Mode simulation, Claude API, and Perplexity API.
• Runs: three independent runs per provider.
• Synthetic target: 10–15 queries per run.
• Mode: API-first hybrid.
• Live research: enabled when authorized and available.

For each provider, first determine whether a documented API route supports the selected model and operation. When the route and configured credential are available, call the real provider API. Use host-model simulation only for a missing credential, unsupported surface, incompatible model, provider failure, or an explicit simulated-only request. Do not downgrade merely because the user did not separately say “use the API.”

The ordinary default plan is at most three runs per provider and 10–15 generated candidates per run. Ask before materially expanding that plan or selecting an unrequested higher-cost model. A user-specified larger plan/model or a model deliberately configured through the documented environment override is already authorization for that configured scope; set expanded_scope_authorized: true only for that explicit larger request, and still surface the model source and compatibility status in the plan.

The 10–15 target applies only to generated candidates. Never pad, truncate, or rewrite a genuine observed trace to meet it. If an observed run returns fewer queries, report the actual count and add separately labeled synthetic candidates only when useful.

Keep each run independent: use the same seed, language, locale, persona, and scope, but never show one run's queries to the next run. For host-model heuristic fallbacks, use isolated subagents, fresh model calls, or fresh contexts when the host supports them. If context isolation is unavailable, describe the sets as repeated prompt variations rather than strictly independent runs and add that limitation to the report.

Select an execution mode

Use the strongest available evidence for each provider, not one global label:

1. API capability gate: confirm a documented provider API route, resolve the selected model, and check the corresponding environment credential without exposing it.
2. Observed tool mode: when the real API exposes structured query strings, collect them verbatim from the documented trace.
3. Provider synthetic mode: when the real provider API does not expose query strings, ask that provider model for plausible candidates and retain its exact model and run metadata.
4. Heuristic simulation: use the current host model only when the named provider API cannot responsibly be called. Mark platform-specific differences as lower-confidence hypotheses.
5. External search signals: use live SERPs, People Also Ask, related searches, trends, or current facts as supporting evidence. Store them outside the platform query trace.

If networking is unavailable, continue in heuristic mode and disclose the limitation. If only one provider fails, continue the others and preserve the failure in the report.

Workflow

1. Analyze the seed

Identify:

• the entity or topic;
• primary and secondary intent;
• meaningful ambiguity;
• likely response type;
• attributes and related topics;
• comparison, recency, context, next-step, trust, action, and risk needs;
• missing context and assumptions;
• whether the task is entity-heavy, journey-heavy, or both.

Do not turn every information need into a query. Keep only searches that would materially help an AI answer the original request.

2. Gather current external signals

When authorized web access is available, inspect current SERPs, visible People Also Ask questions, related searches, and time-sensitive facts. Store source URL, source title, retrieval time, language, locale, and signal type in external_search_signals. Use these as evidence for intent and coverage, never as proof that a named model executed a query.

When a URL is supplied, fetch it with the host's browser or URL tool. Do not pass an arbitrary page URL through a credential-bearing provider script. If the page is inaccessible, ask for pasted content and continue the query analysis separately.

3. Detect API capability and execute API-first

Read references/provider-capabilities.md. Resolve models in this order: an explicit request model, the documented environment override, then the tested default.

Build the collector plan before network calls. Set network_access: false for an explicit offline/no-network request and allow_paid_api_calls: false for an explicit no-paid-API request. Set expanded_scope_authorized: true only when the user explicitly requested more than three runs per provider or more than 15 generated candidates per run. simulated_only also disables provider calls. For each provider, inspect:

• whether a documented API execution route exists for the selected product surface, separately from any simulation route;
• the exact requested model and whether it is a documented default, requires provider verification at call time, or is clearly incompatible with that provider;
• whether the corresponding credential environment variable is available;
• whether the run will use a real provider API, host simulation, or a hard failure in observed_only mode;
• planned initial calls, retry/continuation upper bounds, possible provider-side search calls, and whether cost can be estimated before token/search usage is known.

Show this safe plan as a non-blocking update. For an ordinary requested or default plan, immediately execute every entry whose will_call_api value is true; do not ask for a separate API or cost confirmation. The collector's --allow-api-calls flag is a deliberate local network gate that the skill supplies automatically after planning, not a request for another user decision.

If a credential is missing in hybrid mode, continue with a labeled host-model fallback. If the user explicitly requires API-backed or observed_only execution, name the required environment variable and wait for the user to set it outside the chat. Do not ask them to reveal its value.

Respect explicit simulated-only or no-network instructions. Ask before execution only when the proposed plan would exceed the user's scope or the ordinary default plan, unless the user explicitly requested that larger scope.

Resolve SKILL_DIR to the directory containing this SKILL.md; do not assume the project working directory is the skill directory. Keep request JSON in memory and pass it through stdin by default. Use the bundled collector when direct provider HTTP access is appropriate:

python3 "$SKILL_DIR/scripts/collect_queries.py" plan -
python3 "$SKILL_DIR/scripts/collect_queries.py" collect - --allow-api-calls

The collector accepts - for stdin, never accepts API keys as arguments, and never writes raw responses. Use a local request file only when the user asks to save it or the host cannot pass stdin safely.

4. Collect three independent runs

• For OpenAI and Gemini, record exact search-tool query strings only from the documented structured trace paths. For Claude, require a server_tool_use ID to have a matching web_search_tool_result.tool_use_id; a pending call at pause_turn is not yet observed.
• For Perplexity sonar-pro, use Pro Search concise streaming and record exact web_search.search_keywords[] strings as observed queries. Keep query counts, search results, citations, and related_questions as separate metadata; never convert them into queries. For model/configuration combinations without that structured trace, label requested query lists in response text as provider-generated synthetic candidates.
• For the consumer Google Search AI Mode surface, generate clearly labeled simulations based on Google's public descriptions and current search signals. A Gemini API call is a provider-backed simulation, not an observed Google Search AI Mode trace.
• In hybrid execution, call every available provider API first. When an otherwise successful observed call omits usable query strings, make at most one planned same-provider call for synthetic_provider_query candidates before using the host model. If a provider key is missing, the selected model is unavailable, both provider paths fail, or no responsible provider fallback exists, generate host-model runs with heuristic_simulation provenance and preserve any prior API attempts. In observed_only mode, record the failure and do not make either simulated fallback.
• Retry only timeouts, HTTP 408/429, and 5xx responses, with no more than two retries. Do not retry authentication or request-shape errors.
• Preserve provider failures and degraded runs instead of silently replacing their models or provenance.
• Record whether an API was attempted and the fallback reason for every run. An observed or provider-synthetic query requires an API attempt; a heuristic simulation requires a non-empty fallback reason.
• Record an actual model ID only when the response exposes it. Otherwise use null plus not_exposed; never copy the requested model into the actual-model field as a guess.

5. Classify every query

Read references/taxonomy.md. Assign:

• one primary construction form;
• one primary information-gap function;
• one journey stage when relevant;
• query language;
• provider, exact model or not_exposed, run number, and provenance.

Use natural retrieval-query wording, not proposed headings or an answer outline.

6. Normalize, deduplicate, and cluster

Read references/clustering-and-scoring.md.

• Apply deterministic exact normalization and deduplication within each run.
• Preserve repeated occurrences across independent runs.
• Cluster semantic equivalents only when they share the same retrieval task, constraints, expected answer, and user stage.
• Keep differences in negation, locale, year, audience, platform, comparison target, price, or risk when they change the information need.
• Keep observed and synthetic members in the same semantic cluster when appropriate, but never erase their individual provenance.

7. Calculate recurrence and cross-model coverage

For each platform cluster, calculate the fraction of that provider's valid analysis runs containing the cluster. For each cross-platform cluster, calculate the fraction of actually participating platforms containing it.

Use high, medium, and low labels only as report heuristics. Show numerators and denominators. Never call either score an adoption probability.

8. Analyze an optional page

When a URL or page content is supplied, read references/url-coverage.md. Compare priority clusters against visible page evidence and label each cluster:

• covered;
• partial;
• missing;
• separate_page_candidate;
• off_page_signal;
• not_assessable.

Do not recommend putting every cluster on one page. Separate a new intent, audience, journey stage, or content format when it would weaken the current page.

9. Recommend page topics for SEO and GEO

Read references/seo-geo-topic-recommendations.md. Always turn the clustered evidence into a short, prioritized set of topics the target page should cover.

• Group related clusters into topic families; do not turn every query into a heading or separate page.
• Default to 5–8 recommendations when the evidence supports that many, and use fewer when the intent is narrow.
• Give every available recommendation a rank, P0, P1, or P2 priority, an action, supporting cross-cluster IDs, supporting external-signal IDs when available, coverage guidance, an SEO/GEO rationale, and a suggested content format.
• Keep P0 topics on the primary page. Use separate_page_candidate for a materially different intent, audience, journey stage, or format, and off_page_evidence for needs the site cannot credibly satisfy with its own copy.
• When no URL is supplied, present recommendations as a proposed content brief, not as claims about what an existing page lacks.
• When a URL is supplied, reconcile the recommendations with page_coverage; do not call an already sufficient topic missing or recommend an unfocused omnibus page.

Store the result in recommended_page_topics before validation. If no usable clusters exist, return not_available with a concise reason instead of inventing topics. The final Markdown section must appear even when URL coverage is unavailable or recommendations are unavailable.

10. Build and validate the report

Build the internal JSON document described in references/output-schema.md and references/report-schema.json. Use report schema 1.2; the collector request envelope remains 1.0. Keep the report in memory by default and validate it through stdin before rendering:

python3 "$SKILL_DIR/scripts/validate_report.py" - --pretty

Fix schema, provenance, duplicate-ID, reference, score, or secret-leak errors before responding. If the user requests JSON or CSV, return or save it only then. Escape spreadsheet-formula prefixes when exporting CSV.

Final response

Return a concise Markdown report with:

1. method, context, models, run count, modes, assumptions, and failures;
2. intent and important information gaps;
3. external search signals when used;
4. provider-specific query clusters and representative original queries;
5. within-provider recurrence;
6. cross-model consensus and platform-specific angles;
7. a coverage matrix;
8. optional page coverage;
9. limitations;
10. as the final section, prioritized topics the page should cover for SEO and GEO.

Follow the display template in references/output-schema.md. Keep observed and simulated provenance visible. Do not expose private reasoning, raw API bodies, credentials, or unsupported platform claims.

Attribution

Author: Span. Licensed under the repository MIT License. Copyright (c) 2026 SpanChenGithub.