Dotnet Explore

---
name: dotnet-explore
description: >-
  Use before changing C#/.NET code when the set of symbols the task touches is not already known —
  surveying an unfamiliar subsystem, assessing how a new feature lands in the existing codebase, or
  finding out what a change would break. Delegates the wide search_index/get_references sweep to the
  plugin's dotnet-explore subagent, which spends those responses in its own context and hands back
  symbolIds, file:line use sites and the blast radius. Read-only: it cannot edit.
---

# Delegating the sweep to dotnet-explore

This plugin ships one read-only navigator subagent, `dotnet-explore`. It turns a prose task into the
symbols it is about: `symbolId`s, use sites, affected files, and how far a change would reach. It
never judges code and it cannot change it — the invoking agent decides what to do with the map.

## Host adapter

Claude Code can launch the bundled `dotnet-explore` custom agent directly. Codex plugins do not
currently install custom-agent registrations. In Codex, launch the built-in read-only explorer and
start its brief with: "Read `<pluginRoot>/agents/dotnet-explore.md` and follow its Markdown body;
ignore only the Claude-specific YAML frontmatter." The file under `agents/` remains the one role
contract; do not copy its body into this skill or a Codex-only agent file.

**Why delegate rather than fan out yourself.** A wide `search_index` plus a `get_references` per
candidate is the single most expensive shape of read this server produces, and almost all of those
tokens are scaffolding you throw away once you know the answer. The agent pays them in its own
context and returns a report a fraction of the size.

## When to invoke it — and when not to

**Invoke it** when the symbol set is genuinely unknown: an unfamiliar subsystem, "how would this
feature land", "what breaks if I change this", a review or refactor whose boundary you cannot yet
name.

**Skip it** when:

- **The symbol is already known.** A two-call lookup is not what this is for; use `dotnet-read`.
- **You need the text, not the map.** The agent never reads a `.cs` file; it reports
  `declarationSites`, and the ranged `Read` over them is yours to make.
- **The answer is in a non-C# file.** `.csproj`, `.json`, `.md`, `.editorconfig` are out of its
  scope; it will say so and stop.

## Step 0 — check readiness before launching

**Call `workspace_status` yourself, before spawning.** The agent checks too, but a cold or degraded
workspace wastes an entire agent run:

- Still loading, or `index_only` → semantic results are unavailable, **not empty**. Wait, or accept a
  syntax-tier map and say so.
- `degraded` (projects failed to load) → the map may be silently **wrong**. Fix the build and
  `reload_workspace` before spawning, or don't spawn.
- Just did a `git pull`/`checkout`/rebase, or added or deleted a `.cs` file →
  `reload_workspace(scope: "all")` first.

## What to tell it

Everything you state is context it does not have to re-derive, and re-derivation is the expensive
part of a cold start.

- **The task in prose** (required): what someone is about to do to this codebase — not "find
  `FooService`", but "we want to add cancellation to the training loop".
- **Any symbol, file, or project you already know is involved.** It will start from there instead of
  guessing search terms.
- **Depth**: "where is this" (a one-hop map, ~8 calls) vs. "what breaks if I change this" (full blast
  radius, up to its 20-call ceiling). Transitive reach costs real tokens — ask for it only when the
  question is about ripple.
- **A `taskId` you want it to use**, if you plan to read its exact cost back with
  `get_retrieval_metrics(groupBy: "task")`. Otherwise it mints its own and reports it.

## Parallelism

One instance per **independent question**, launched in a single message. Do not split one question
across instances — the second would re-derive the first's search terms from scratch, and each cold
start re-pays the whole baseline. Two genuinely separate subsystems is two instances; one subsystem
explored "twice as thoroughly" is one.

## Reading its report

Fixed sections: **Target**, **Entry points**, **Blast radius**, **Affected files**, **What would need
to change**, **Suggested next calls**, **Not covered**.

- **`symbolId`s are the payload** — paste them straight into `get_symbol`, `get_references` or
  `rename_symbol`. A `symidx_` prefix is provisional (syntax tier) and a `symfb_` one is not a fetch
  target at all (a local function, a lambda, a symbol with no doc-comment id); the report flags
  those on the row.
- **Read `Not covered` first, not last.** It is mandatory and carries `limitedBy` verbatim, budget
  stops, non-C# files the answer touches, and any ambiguity it resolved on your behalf. A map that
  says where it ends is useful; one that looks complete is dangerous.
- **`Suggested next calls` names the write path but never performs it.** Verify a suggested call
  against the actual schema before running it.
- **It reports locations, not conclusions.** No quality judgments, no design opinions, no proposed
  diffs. If it offered one anyway, treat it as noise.

## Then what

The map is the input to a change, not the change. Invoke **`dotnet-write`** next: its step 2 —
`Read` the exact declaration span, then `Edit` anchored on that text — is exactly the step the agent
deliberately did not do for you.