ByteTerrace/Puck / .claude/skills/symbol-analysis
symbol-analysis
VerifiedAnswers C# structure questions with puck references and declarations: which types derive from, implement or override a symbol, who references it, safe to delete or rename. Text: content-search.
SKILL.md
View on GitHub---
name: symbol-analysis
description: "Answers C# structure questions with puck references and declarations: which types derive from, implement or override a symbol, who references it, safe to delete or rename. Text: content-search."
---
# Symbol analysis
Use compiler-backed evidence for C# structure. Text matching cannot resolve
aliases, overloads, extensions, generic instantiations, or name collisions.
Treat repository-specific examples as snapshots; re-run the command against the
current tree before relying on one.
| Question | Command |
|---|---|
| Who references it, is it dead, is a delete safe | `puck references <name> --no-doc`, then `puck search -M 0 -l <name>` for files no project compiles; build the affected projects before declaring a delete safe |
| What implements this interface or member | `puck references <name> --implementers` |
| What overrides this member | `puck references <name> --overrides` |
| What derives from this type | `puck references <name> --derived` |
| Two same-named symbols: which is which | `puck references <name> --declarations`, then narrow with `--containing <namespace-or-type>` |
| What a file or tree declares, members, base lists, attributes, crefs | `puck declarations --members <path>` (add `--kind`, `--name`, `--base`, `--attribute`, `--doc`); parse-only, so it needs no build and sees uncompiled files, but proves no usage |
| Literal, config or non-C# content | `content-search` |
| Whether a refactor still compiles | Build the affected project |
| `.puck` DSL name resolution (state, prototype, placement, camera names, imports) | Neither verb parses `.puck`; use `puck lint` (`PUCK_LINT_00x`) and the DSL's LSP, see `puck-dsl` |
## Start the CLI from a clean checkout
Run from the repository root with the checkout's own CLI build, never a
published copy or the global `puck` tool, both of which lag the head. Copy
`src/Puck.Cli/bin/Release/net11.0/` to a scratch directory named for your lane
and run the copy, so the running tool never locks the build output another
build needs:
```text
dotnet <lane>-cli/Puck.Cli.dll <verb> <arguments>
```
If that build is absent, build it (`dotnet build src/Puck.Cli -c Release
-nodeReuse:false`) and copy it
([verification](../verification/SKILL.md#run-verbs-from-your-own-cli-copy));
`dotnet run` on the project runs the build in place and locks its output, so it
is not a substitute for the copy.
`references` loads the whole solution. A fresh worktree is unrestored, and the
load then fails with exit 2 and a message counting the projects that carry no
`obj/project.assets.json`: run `dotnet restore Puck.slnx -nodeReuse:false` at the
worktree root and retry. `declarations` needs neither a restore nor a build.
## Evidence rules
- Inventory a family with `declarations`, then query named symbols one at a
time. An empty-name `references "" --contains --containing <family>` can
retain gigabytes of workspace and reference state while searching every
matching member; narrowing the containing name does not make that broad
query cheap. Use `search` for a textual family inventory.
- `references` loads a project graph and resolves symbols. Narrowing with
`--project` changes the closure and therefore the question.
- Read the definition on each `ref` line: it is the resolved symbol, which is
not always the one queried. Constructing a type reports under its constructor,
and an interface-dispatched call reports under the interface. `--strict` keeps
only the queried symbol's own group, so it hides every construction site.
- Documentation `cref` locations count as references; `--no-doc` drops them. A
symbol whose only references are crefs is a dead-code candidate.
- A symbol that looks unused by name can be used through an extension method or
a `using` alias, and one that looks used can be a name collision. Check the
member, not only the containing type (`AllocatorExtensions` has no references
while its `Alloc` method has many).
- Rename safety: a text count undercounts, because a `using Alias = ...;`
hides the type's name at its uses. Take the `references` list, then build the
affected projects after the rename; the compiler is the full check.
- `references` cannot see files no project compiles (the quarantined
`experimental/` trees, file-based apps). "Zero references" means zero compiled
references: pair a deletion decision with `puck search -M 0 -l <name>`.
- `declarations` parses syntax without a build and can see those files, but it
matches names and cannot prove semantic usage. A missing path is an error
(exit 2), never an empty inventory.
- A partial workspace load is not a clean answer. Use `--allow-partial` only
when explicitly accepting and reporting incomplete evidence.
- Inspect ambiguity and resolved-definition output before acting on a short
symbol name. Several `partial` declarations of one type report one line each.
- `references`/`declarations` parse the C# project graph only; nothing in
`Puck.Cli`'s analysis verbs parses `.puck`. Treat a `.puck` name question as
out of scope rather than assuming a text search is the only fallback.
## Load the full reference selectively
Read [references/complete-reference.md](references/complete-reference.md) for
exact flags and output, solution/project closure traps, documentation behavior,
generated and inactive-code limits, verified edge cases, and the Release-mode
file-based Roslyn app fallback.
## Related skills
| Question | Skill |
|---|---|
| Literal, config or non-C# text; exhaustive file lists | `content-search` |
| `.puck` name diagnostics, `puck lint` | `puck-dsl` |
| Whether a deletion or rename also leaves stale docs | `boy-scout` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |