version: "1.0.0" name: dotnet-symbols description: "Find .NET/C# Agent Framework (MAF) declarations and Go SDK counterparts with symbolmap. Use for symbol lookup, declaring namespaces, overloads, .NET-to-Go porting or parity reviews, unreviewed declarations, and symbol mapping updates or validation." argument-hint: "A .NET type/member, qualified Go symbol, or API comparison"

.NET and Go symbol lookup

Look up declarations before inferring a counterpart. Keep symbol lookup read-only: do not edit the mapping, regenerate the inventory, or expand the .NET package scope unless requested.

1. Choose the right query

Run from the repository root with its Go toolchain. Start with a filtered CLI query, not a full read of either JSON file. Substitute the requested name for the examples below.

mappings searches .NET assessments; go-only searches separately reviewed Go-specific APIs. For declaration discovery, use reconcile without status/state filters so both reviewed and unreviewed APIs remain visible; use -state unreviewed only for the review queue. 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 counts only, use mappings -summary or reconcile -summary. 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.
• 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 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 dependencies. If indexing is unavailable, use scoped source/data reads and label what remains unvalidated; do not alter dependencies or regenerate the inventory merely to answer a lookup.

3. Verify evidence and answer

• Read status and note for the exact leaf. go_symbols records counterparts; 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 references resolve, not behavioral parity; unreviewed means no assessment, not unmapped. 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. Read each entry's note and required named review; 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 generated inventory covers three core .NET packages, not every integration or external dependency. 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. A leaf's review selects reviews[review]; absence selects baseline, not the containing type's review. Check inventory/build provenance, review_source_changed, review_go_changed, and Go dirty state before presenting an old assessment as current. 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 assessed leaf under its declaring namespace/type and exact overload. Keep go_symbols, status, and a concrete note; do not promote a name suggestion into a mapping without source evidence.
• 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 existing reviews and baselines; record newly inspected work in a separate review batch. Never hand-edit the generated inventory or maintain a second mapping in the skill.
• For a confirmed Go-specific API, use a canonical Go symbol key under go_only with note and review, 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.

After mapping-only changes, run go run ./cmd/symbolmap reconcile -summary -check. Run go test ./cmd/symbolmap and go vet ./cmd/symbolmap when changing the command's Go code, not for catalog-only edits. Strict checks inspect the whole unfiltered report; 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.
• Reviewed mapping: scoped assessment edits.
• Generated inventory: canonical CLR identities and package/assembly provenance.
• Extractor guide: pinned regeneration, only when requested.