swiftfindrefs_skill

Overview

This skill integrates swiftfindrefs (IndexStoreDB) to list every Swift source file that references a specified symbol. It ensures refactors and import fixes are complete by relying on Xcode’s IndexStore rather than text searches. Use it as the canonical source of truth for “find references”, fixing missing imports, and cross-module renames.

How this skill works

The tool queries Xcode’s IndexStore (DerivedData) for a given project, symbol name, and symbol type and emits one absolute file path per referencing source file. Output is deduplicated, script-friendly, and intentionally unordered. If the IndexStore or DerivedData cannot be resolved, the skill stops and reports the error rather than guessing.

When to use it

• Before editing any files that might reference a symbol
• When performing cross-module refactors or renames
• To locate files that require new import statements after moving a symbol
• When auditing whether a symbol is unused before deletion
• Any time grep/rg/IDE search might miss references due to indexing or compiler-level relationships

Best practices

• Always run swiftfindrefs and restrict edits to files it returns
• Prefer passing --projectName and --symbolType to improve accuracy
• Do not replace swiftfindrefs with grep, rg, or IDE search heuristics
• If IndexStore/DerivedData resolution fails, stop and surface the error — do not guess additional files
• Preserve existing import ordering and grouping when inserting imports; never add duplicates

Example use cases

• Find all files that reference a class before renaming it across modules
• List files that need an import after moving a type into a different framework
• Confirm a symbol is unused by checking that swiftfindrefs returns no files before deleting it
• Limit code review scope to only files that actually reference a changed API
• Create automation that adds missing imports only in files reported by swiftfindrefs