.NET and Go symbol lookup

Look up declarations before inferring a counterpart. Keep symbol lookup read-only: do not edit the catalog, extract assemblies, refresh declarations, or expand the .NET package scope unless the user explicitly asks. Declarations, extraction metadata, assessments, and test identities share one maintained catalog.

1. Choose the right query

Run from the repository root with its Go toolchain using the independent catalog module, github.com/microsoft/agent-framework-go/_catalog. The SDK does not require or replace it. The nested module boundary excludes its tooling and data from the SDK module ZIP; the underscore prefix alone only skips package discovery. go -C _catalog changes the process working directory to that module: -file defaults to the single catalog basename and -go-root to .. (the SDK parent). Explicit path flags are relative to that directory or can be absolute. Start with a filtered CLI query, not a full catalog read. Substitute the requested name for the examples below.

mappings includes assessed leaves and extracted unreviewed placeholders by default; use -assessed for reviewed outcomes. go-only searches separately reviewed Go-specific APIs. For declaration discovery, use reconcile without -assessed or status/state filters so both reviewed and unreviewed APIs remain visible; use -state unreviewed only for the review queue. gaps always excludes unreviewed placeholders and selects assessed partial/unmapped leaves. go reads the Go module independently of the catalog. changes -old-root <checkout> compares structural Go APIs without changing either assessment section; retain compatible additions and review source diffs for behavior.

For assessed counts, use mappings -assessed -summary or reconcile -assessed -summary. For all declarations, omit -assessed; mapping summaries include an optional unreviewed_symbols count. mappings, gaps, and reconcile accept -assessed. reconcile and tests read only the catalog selected by -file, with no -inventory flag. There is no standalone summary command. Flags follow the subcommand; use its -help to check supported options.

2. Resolve the exact declaration

• -namespace, -type, and -symbol are case-insensitive substring filters, not exact matches. Combine them with -kind when needed, quote names containing generics or spaces, and inspect the returned declaring namespace and full overload. -symbol also searches Go snippets and targets. Inherited members belong to their declaring base type.
• Every API method key includes -> ReturnType, including void, declared async wrappers, and method-generic returns; do not unwrap async returns. Constructor keys, property keys, and test names remain unchanged.
• JSON is the default: read mappings for catalog results, rows for reconciliation, and symbols for the Go index. Pages default to 20 rows; the examples request five. Follow page.next_offset with the same filters and limit while inputs remain unchanged. Stop when the requested declaration is resolved; traverse all pages only for an exhaustive request. Use -limit=0 only for a requested full export. Summary counts cover all filtered matches and reject paging flags.
• If a mapping query has page.total: 0, check go-only for a Go symbol and reconcile for the containing .NET type without -assessed or status/state filters, then broaden the query and check declaring ownership. An empty page with a nonzero total can mean the offset is past the end; retry at offset zero. Neither case proves an API is absent from Go.
• Treat command failure separately from zero matches: inspect stderr and the exit status. go and reconcile index offline and require cached SDK dependencies, prepared with go mod download from the repository root. Tooling dependencies are separately prepared with go -C _catalog mod download; go-tests is static and does not load SDK dependencies. If indexing is unavailable, use scoped source/data reads and label what remains unvalidated; do not alter dependencies or run extraction merely to answer a lookup.

3. Verify evidence and answer

• Read status and any note for the exact assessed leaf; mapped entries normally omit redundant notes. An extraction-added unreviewed: true placeholder stores status: unmapped, empty go_symbols, an empty non-property go, and no note; it is not an assessed gap. For assessed leaves, go_symbols records counterparts and go is illustrative code, not a standalone program. Free variables are allowed and their receiver/argument types are not fully checked. Verify Go signatures and actual callers before using a snippet in an implementation. Properties intentionally have no example.
• Reconciliation state is not mapping status: linked means assessment references and targets resolve, not implementation or behavioral parity; unreviewed means no assessment and its report status is omitted, regardless of the stored placeholder status. suggested_go is only a name-based search hint. A mapped type does not cover all its members.
• go_only records source-reviewed Go-specific APIs, not unmatched names or missing inventory coverage. Each entry contains only a concrete note; a type entry does not cover its members. Reconciliation checks these Go targets separately without adding .NET rows or certifying absence of a counterpart.
• The catalog's API extraction covers three core .NET packages, not every integration or external dependency. Existing out-of-scope assessments are retained without being treated as current extracted declarations; this is not a missing feature, and outside-inventory-scope is not evidence of removal. go-outside-scope means a target package was not indexed. Go results cover the reported build configuration, not every platform. An unresolved identity or unvalidated target is not a confirmed implementation gap.
• For a behavioral claim, inspect .NET source at the applicable recorded revision and compare the Go implementation, callers, and tests. The original baseline is historical provenance, not the latest inspection of every assessment. The catalog has no named review records or per-leaf review references; later inspection evidence belongs in PR discussion and Git history. Automatic placeholders establish no assessment against the baseline. Check dotnet extraction/build provenance, review_source_changed, review_go_changed, and Go dirty state before presenting an old assessment as current. The change flags compare revisions only with the original baseline, not a per-leaf latest inspection, and do not certify behavior. Missing change flags are unknown, not proof of an unchanged revision.

Answer concisely with the exact .NET declaration, recorded Go counterpart(s), and the relevant assessment or scope limitation. Cite source and revision for behavioral claims; distinguish recorded mappings from newly verified behavior. Do not dump the full JSON response or describe unreviewed/out-of-scope entries as missing features.

4. Update only when requested

• Change only the assessment fields of the leaf under its declaring namespace/type and exact overload. Keep go_symbols and status; normally omit note for mapped, but require a concrete explanation for other assessed statuses. Remove unreviewed when actually assessed. Preserve dotnet metadata, declaration keys, assembly/kind, and extraction markers (identity, experimental, compiler_generated, unavailable). Do not promote a name suggestion into a mapping without source evidence. Class kind and current scope membership are defaults; full reflection metadata is not repeated in the catalog. Add or rename declaration keys only through an explicitly requested extraction refresh.
• Non-property go examples use minimal calls or literals, conventional variables, and new(value) for pointers—not synthetic outer functions or unrelated fields. Real callbacks may remain. Property leaves omit go entirely.
• Preserve the original baseline; record newly inspected revisions and evidence in PR discussion and Git history, not new catalog review records. The extraction hash identifies the raw snapshot, not the catalog file. Never hand-edit extraction metadata or maintain another inventory, mapping, or count list in the skill. Only an explicit user request for extraction or refresh justifies dotnetsymbols; normal stdout is transient raw schema-1 ecma335-v1 JSON with full matching metadata. -update-mapping refreshes an existing compact schema-0 catalog instead of emitting JSON, and -input accepts only cached raw schema-1 extraction offline; without an update it still emits raw schema-1 stdout. Refresh completes method return labels with the existing generic names while preserving assessment values; constructor keys, property keys, and test names stay unchanged.
• For a confirmed Go-specific API, use a canonical Go symbol key under go_only with only note, not an invented .NET leaf. Use adapted for equivalent Go composition. Go-only entries cannot also be recorded counterparts; remove an entry when its API is deleted or a .NET counterpart is verified, with evidence in the PR.
• Test identities use exact assembly/full CLR type/name keys with a unique Go test string or null when unpaired, never per-test notes or review objects. Pair only direct ports of the primary setup, entrypoint, cases, and assertions, with minor language-required differences; similar coverage or an analogous added subtest is not enough. Preserve existing Go test names, not CLR-aligned renames. Extractor refreshes preserve existing pairs. go-tests remains standalone source discovery, independent of the catalog; there is no stored Go-test review queue or classification list.

After API assessment changes, run go -C _catalog run ./cmd/symbolmap reconcile -summary -check; after test-pair changes, use go -C _catalog run ./cmd/symbolmap tests -summary -check. Run go -C _catalog test ./cmd/symbolmap and go -C _catalog vet ./cmd/symbolmap when changing the command's Go code, not for catalog-only edits. Strict checks inspect the whole unfiltered report, even with -assessed or pagination; a paged result or zero exit status does not establish behavioral parity or complete package coverage.

References, loaded as needed

• Mapping guide: schema, statuses, and CLI contracts.
• Single catalog: declaration labels, exceptional identity overrides, dotnet provenance, assessments, and test identities/pairs; only assessment fields are hand-edited.
• Shared catalog model: schema source of truth for both commands.
• Extractor guide: read-only extraction smoke checks and explicit pinned or cached refreshes, only when requested.