---
name: cse-sweep
description: Fan out gpt-realtime-2.1-mini navigators over CSE platforms (Jira, Confluence, Slack, Kepler/Gong/email, Granola, KG), score evidence shards on gpt-realtime-2.1-mini, and synthesize one gpt-5.6-terra narrative (low reasoning, priority tier). Use for open-ended, cross-platform research or an explicitly requested deep narrative; routine known-person, account, or ticket retrieval uses context_assemble instead. Read-only; writes only to a run dir (default ~/.cse-tools/sweep-runs/<ISO>/, or a path passed via --out).
argument-hint: "[--topic \"...\"] [--accounts A,B | --emails E1,E2 --people N1,N2 | --tickets K1,K2] [--mode evidence|strategy] [--audience WHO] [--since ISO] [--until ISO] [--max-pack-tokens N] [--dry-run] [--smoke] [--out DIR]"
---

# cse-sweep

## Compact MCP routing

Interactive agents follow the shared [MCP routing contract](../../shared/compact-mcp-routing.md) and default to `http://127.0.0.1:9901/mcp/full`. This skill's programmatic scripts use the same full plane (override with `CSE_SWEEP_MCP_URL`) under their read-only exemption; they drive named tools directly, discover live schemas, and enforce a pinned navigator allowlist. Compact `/mcp` remains available to facade-only compatibility clients.


Fan out a panel of gpt-realtime-2.1-mini navigators over the CSE platform surface, score the resulting evidence shards on gpt-realtime-2.1-mini, then synthesize everything in one gpt-5.6-terra Codex Responses call (reasoning effort low, service_tier priority). Every model call runs on the shared always-on rtinfer endpoint served by `cse-toold serve`, so the skill never opens its own realtime/Codex connection and carries no model auth.

Use when the research target is open-ended or the requested output is a deep, synthesized narrative: "sweep everything on Guardian Life renewal risk," "build a deep dossier on this CSE," or "what do we know across platforms about X."

For routine retrieval on a known person, account, ticket, or operator, call `context_assemble` directly. Do not invoke sweep merely because several sources may be relevant. Person-, account-, or ticket-scoped sweep is appropriate only when the operator explicitly wants deep research and a narrative product. Exact board state, fields, or verbatim quotes remain precision capability reads, not sweep output. See the shared [read strategy](../../shared/read-strategy.md).

## Hard boundaries

This is a read-only gather/synthesize tool. It performs no external writes:

- No Jira create/edit/comment/transition.
- No Confluence create/update/reparent.
- No Slack post/update/reaction/DM.
- No customer-facing message.
- No Kepler/Gong/email send.

The only thing it writes is the run directory: shards, seed text, branch manifest, the business brief, and the final `answer.md`. That dir defaults to `~/.cse-tools/sweep-runs/<ISO>/` (override with `CSE_SWEEP_RUNS_DIR`) or a path the operator passes via `--out`.

## Business brief (account scope)

An account-scoped sweep also gathers a short public-web brief on the account: five labelled
lines (**What they do**, **How they make money**, **Why APIs matter**, **Recent and
upcoming**, **Regulatory context**). The public-web brief covers the first three
accounts of an account sweep; accounts past that cap are named in the render when they
fit, with an explicit remaining count when every name would break the hard word cap, so
they are never dropped silently. The brief's
`identity` is `confirmed`, `unknown`, or `ambiguous`; no field can be `ok` unless a
provider-cited IDENTITY URL confirms the normalized full company name. Missing,
mismatched, or ambiguous identity makes all five fields explicit unknowns. It runs through
the read-only `web_business_brief` MCP tool (hosted web_search as the lane's only
external search path, with no third-party provider such as Exa; daemon-owned transport)
alongside the internal fan-out. Sourced entries require URLs from authoritative provider
evidence: official Responses `url_citation` annotations or pages reported in provider
`web_search_call.action.sources` lists; model prose is never evidence. That proves
retrieval/provider evidence, not independent semantic fact-checking of every generated
claim. Direct MCP output remains `unverified: true` and must be confirmed before external
use. API analysis is explicitly source-free and visibly labelled; regulatory
silence, absence, and negative claims degrade to unknown, never "unregulated."

The sweep strictly revalidates the tool payload and Markdown-escapes rendered text. One
aggregate 240-word visible cap covers the entire Business brief, including labels and
unknowns; an account that cannot fit is named in the render rather than silently dropped.
The rendered section carries no provenance footer: per-claim `([source](URL))` links and
the `Analysis (no public source states this):` label do that work inline. The normalized
`business-brief.json` artifact retains validated brief fields and sources; it has no
`note` field. Public web evidence stays
isolated from internal evidence: it is never scored, packed into synthesis, mixed into
shards, or added to the internal `## Sources` list. It appears as a cited `## Business
brief` section at the top of `answer.md`, with the raw result in `business-brief.json`.
Person- and ticket-scoped sweeps skip it. `CSE_SWEEP_BUSINESS_BRIEF=0` disables only this
sweep lane, not direct `web_business_brief` MCP reads; a public-web failure is recorded
and never fails the run.

## Requirements

- Node 20+ (checked by the sweep launcher).
- The local cse-toold MCP plane running at `http://127.0.0.1:9901/mcp/full` (checked by the sweep launcher). Source the bootstrap first so `CSE_TOOLD_BIN` resolves: `source "${PLUGIN_ROOT:-${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$PWD/plugins/cse-tools}}}/.agents/shared/skill-bootstrap.sh"`. The daemon keeps keychain auth fresh on its own; if a tool returns 401, request `cse_session_info({"force_refresh": true})` once and retry.
- The shared always-on rtinfer endpoint: a loopback `/v1/infer` listener (the `rtinfer/1` contract) served by `cse-toold serve` and advertised via `~/.cse-rtinfer/endpoint.json`. Serves the warm realtime navigator/scorer pools and the `responses_text` synthesis tier. cse-sweep selects gpt-5.6-terra for its final synthesis request; this does not change a shared daemon fallback. All model calls run server-side (no per-skill Codex auth; Codex OAuth slots live in the daemon's SE-encrypted cred store). This is the only inference path; if no rtinfer endpoint is reachable, the run fails loud with a `daemon-unreachable.json` marker in the run dir rather than degrading to seed-only shards. Discovery order: `$CSE_RTINFER_URL` → `~/.cse-rtinfer/endpoint.json`.

## Usage

```sh
SKILL_DIR="${PLUGIN_ROOT:-${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$PWD/plugins/cse-tools}}}/.agents/skills/cse-sweep"

# Plan only (no models, no network beyond the MCP ping):
"$SKILL_DIR/scripts/sweep.sh" --dry-run --topic "guardian life renewal risk" --accounts "Guardian"

# One branch end-to-end against a known account (cheapest live run):
"$SKILL_DIR/scripts/sweep.sh" --smoke --topic "guardian life renewal risk" --accounts "Guardian"

# Full fan-out:
"$SKILL_DIR/scripts/sweep.sh" --topic "guardian life renewal risk" --accounts "Guardian" --since 2026-05-01

# Person-scoped deep research (email is authoritative; name improves Slack search):
"$SKILL_DIR/scripts/sweep.sh" --topic "expertise, customer influence, and active workload" \
  --emails "alex.rivera@example.com" --people "Alex Rivera" --since 2026-05-01

# Ticket-scoped:
"$SKILL_DIR/scripts/sweep.sh" --topic "integration blocker" --tickets CSE-123,CSE-456

# Topic scope (no accounts/emails/tickets): internal-knowledge questions.
# Plans kg/jira/confluence/slack/granola/calendar; excludes account-required
# Kepler tools that reject or descope empty customer filters.
"$SKILL_DIR/scripts/sweep.sh" --topic "how should we structure CSE onboarding" --since 2026-05-01

# Strategy mode: business commentary (thesis + patterns + play + optional draft
# copy) instead of an evidence report. Same gather, same citations; only the
# final synthesis contract changes. Works with account or topic scope.
"$SKILL_DIR/scripts/sweep.sh" --mode strategy --audience "GTM leadership" \
  --topic "how should we position Top-100 CSE outreach" \
  --accounts "GoodLeap,DigiCert" --since 2026-06-01

# Custom output dir:
"$SKILL_DIR/scripts/sweep.sh" --topic "..." --out ~/sweep-runs/guardian
```

Output: `<run_dir>/answer.md` (the gpt-5.6-terra synthesis), `<run_dir>/shards/*.json` (per-navigator evidence), `<run_dir>/seed.md`, `<run_dir>/branches.json`.

## Env knobs

| Env | Default | Purpose |
|-----|---------|---------|
| `EXPLORE_RT_NAV_MODEL` | `gpt-realtime-2.1-mini` | navigator model |
| `EXPLORE_RT_SYNTH_MODEL` | `gpt-realtime-2.1-mini` | shard scorer/dedup model |
| `CSE_SWEEP_RESPONSES_MODEL` | `gpt-5.6-terra` | final synthesis model (low reasoning + priority tier server-side) |
| `EXPLORE_RT_NAV_COUNT` | `8` | parallel navigators |
| `EXPLORE_SEARCH_DAEMON_POOL` | `4` | warm pool size |
| `CSE_RTINFER_URL` | (discovery) | rtinfer endpoint base URL override |
| `CSE_SWEEP_MCP_URL` | `http://127.0.0.1:9901/mcp/full` | MCP plane URL (named-tool compatibility) |
| `CSE_RT_REASONING_STEER` | `Respond quickly, do not reason.` when unset | navigator and scorer prompt prefix; empty disables it, nonempty overrides it |
| `CSE_RT_NAV_REASONING_EFFORT` | (omitted) | navigator-only explicit reasoning effort; unset or empty omits it, nonempty forwards it |

Scope is bounded to 25 accounts, 50 tickets, five people, and 32 navigators per run. `--max-pack-tokens` accepts 1000-1000000 (default 230000).

## How it works

1. `branch-plan.mjs` deterministically expands topic + scope into a manifest of `{platform, subject?, query, arguments}` branches. Scope kind is inferred: person (`--emails`), account (`--accounts`), ticket (`--tickets`), or topic (bare `--topic`). Person scope uses `context_assemble(kind=person)` as the identity-aware backbone, then adds exact participant Kepler, deep Granola, and person-needle Slack branches. Topic scope plans the six-platform internal set (kg/jira/confluence/slack/granola/calendar) and never emits empty `customer_names`/`customers` arrays. `--dry-run` prints `scope=<kind>` plus the manifest without models.
2. The orchestrator seeds the run by running one MCP `tools/call` per branch in parallel (Jira JQL, Confluence CQL, Kepler comms, semantic search, Granola, KG, Slack, Calendar — whichever the scope planned).
3. `nav-loop.mjs` fans out K gpt-realtime-2.1-mini navigators over the shared cse-toold rtinfer warm pool (`POST /v1/infer`, tier `realtime_structured`). Each navigator gets a distinct facet of the question, calls the hosted `cse_query` tool once (which runs read-only JS against the MCP plane), and returns a shard. If the endpoint is unreachable the run fails loud (no live fallback). Topic navigators keep the full read-only tool surface so they can drill into accounts a topic surfaces.
4. `scorer.mjs` dedups findings (Jaccard) and scores each shard 0-10 on gpt-realtime-2.1-mini via the same daemon. Scoring is best-effort: if the daemon drops out here, shards keep their order and the run still synthesizes.
5. `synthesize.mjs` packs all shards + the question and calls the daemon's `responses_text` tier with cse-sweep's gpt-5.6-terra default (server-side auth). Scope is forwarded as `--scope`; topic sweeps use a neutral internal-research contract instead of the CSE-engagement filter. If packed input exceeds `--max-pack-tokens` (default 230000), it map-reduces: synthesize per shard-group, then synthesize the group-summaries.
6. `--mode strategy` swaps only the final-synthesis contract: `answer.md` becomes opinionated business commentary (`## Thesis`, `## What the evidence shows`, `## The play`, optional `## Draft language`, `## Sources`) with the same citation discipline; `--audience` tunes the altitude. Default `--mode evidence` is unchanged, and the map (group) phase stays factual in both modes.

Person mode requires `--emails`, accepts matching optional `--people` labels, allows at most five people, and cannot be mixed with account or ticket scope. Navigators are restricted to participant-bounded communications, Granola, Slack, and calendar reads; account-only semantic/KG/Salesforce tools remain unavailable. Topic mode needs no extra flags.

## Operator voice

No emojis, no coaching register, no filler in any rendered string. The synthesis prompt pins this; keep it when editing.