symbol-surgery
Skill2 starsChanged 59 days agoMITView on GitHub
Symbol-first refactoring discipline using the native LSP tool — locate by symbol, check blast radius before changing, edit at symbol boundaries, verify references after. Use when renaming, changing a signature, moving/extracting/inlining, or deleting code that other code depends on; or whenever the question is "where is this used and what breaks if I change it?" Mechanical-execution complement to `deepen` (which decides what to refactor) and `simplify` (which decides what's clean).
In this repository14 other files it gives its agents.
- adapters/AGENTS.mdAGENTS.md
- adapters/CLAUDE.mdCLAUDE.md
- blast-radiusSkill
- deepenSkill
- diagnoseSkill
- dispatch-waveSkill
- evidence-auditSkill
- grill-with-docsSkill
- session-closeoutSkill
- shipSkill
- tddSkill
- triageSkill
- write-a-skillSkill
- zoom-outSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Use when the change touches code other code depends on:
- Very specific: line 28
All operations take filePath, line, character (1-based).
- Distinctive: line 73
After the edit, confirm the change is complete and consistent:
- Very specific: line 77
Delete: findReferences returns zero (it should, since step 3 proved it).
- Distinctive: line 79
Don't declare a refactor done until the references say it is.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Symbol Surgery
The execution discipline for refactors. deepen decides what module should change and simplify decides what's clean; this skill governs how the change lands — precisely, with the blast radius known before the first edit.
The whole point: stop reaching for Grep-then-guess-line-numbers by reflex. You already have a Language Server in this harness (the LSP tool). Symbol-granular navigation and scoped editing beat text search on precision and on tokens — no whole-file reads to locate a symbol, no broken call sites discovered after the fact.
This is the part of Serena worth keeping: symbol-first, blast-radius-aware editing. The 40-language server management is not — the native LSP tool already covers navigation in-process, with no MCP roundtrip.
When to use
Use when the change touches code other code depends on:
- Rename a function, class, type, variable, export.
- Change a signature — add/remove/reorder params, change return type.
- Move / extract / inline a symbol across files.
- Delete a symbol you believe is unused.
- Answer "where is this used and what breaks if I change it?"
Skip it for: greenfield writing, a self-contained local edit where you already hold the full context, or non-code text. Don't run heavy navigation on a one-line tweak.
The native LSP operations
All operations take filePath, line, character (1-based). workspaceSymbol also takes query.
| Need | Operation |
| Find a symbol's definition | goToDefinition |
| Find every use of a symbol | findReferences |
| Type / doc at a position | hover |
| All symbols in one file (with ranges) | documentSymbol |
| Find a symbol by name across the repo | workspaceSymbol (always pass query) |
| Implementations of an interface/abstract | goToImplementation |
| Who calls this function | incomingCalls (after prepareCallHierarchy) |
| What this function calls | outgoingCalls |
Process
1. Locate — never guess a line range
To act on a symbol, first get its real identity and span:
- In a known file:
documentSymbolreturns every symbol with its range. Edit at those boundaries. - By name across the repo:
workspaceSymbolwithquery. - Unsure what a name refers to:
hover/goToDefinition.
This replaces reading the whole file to find where something lives.
2. Blast radius — before you change anything
For any rename, signature change, move, or delete, enumerate callers first:
findReferenceson the symbol → every use site.incomingCalls(viaprepareCallHierarchy) → the call graph reaching it, when references alone undersell the coupling.
This is the step that prevents the classic "renamed it, broke six call sites you didn't know about." If the reference list is larger than expected, that is the finding — surface it before editing.
3. Edit at symbol scope
The symbol-level editors Serena ships are compositions of tools you already have. Use these recipes:
- Replace a symbol's body →
documentSymbolto get the range, thenEditthat range. Don't hand-count lines. - Insert before/after a symbol →
documentSymbolfor the boundary, thenEditat it. - Safe-delete →
findReferencesto assert zero callers (or migrate them first), thenEditto remove. Never delete on the assumption it's dead — prove it. - Rename / signature change → edit the definition, then
Editevery site from step 2. The reference list is your checklist.
4. Verify — references, not vibes
After the edit, confirm the change is complete and consistent:
- Rename:
findReferenceson the old name returns zero; the new name returns the count you expected. - Signature change:
hover/ type-check resolves at the call sites you touched. - Delete:
findReferencesreturns zero (it should, since step 3 proved it).
Don't declare a refactor done until the references say it is.
When LSP isn't available
The language server must be configured for the file type, or the operation errors. If it's unavailable, fall back to Grep for navigation — but say so, and treat the blast radius as approximate. Grep finds text matches, not semantic references: it misses re-exports and aliasing, and it produces false hits on comments and same-named-but-unrelated symbols. State the reduced confidence rather than implying full coverage.
Relationship to other skills
deepen— decides which modules should be reshaped (depth/leverage). Hand its chosen refactor to this skill to execute.simplify— code-quality cleanups on a diff. This skill is how those cleanups land safely when they cross call sites.diagnose— when the refactor is in service of a bug, diagnose first, then operate.blast-radius— what breaks where references stop: wire formats, data at rest, library internals, consumers outside the repo. Run it when the reference list looks clean and the change still feels risky.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

