swiftfindrefs

Use swiftfindrefs (IndexStoreDB) to list every Swift source file referencing a symbol. Mandatory for “find references”, “fix missing imports”, and cross-module refactors. Do not replace with grep/rg or IDE search.

Security Scan

The skill is internally consistent: it only instructs use of the swiftfindrefs tool to locate Swift references, asks for no unrelated credentials, and does not auto-install or exfiltrate data — review the third‑party brew tap before installing the binary on your machine.

Purpose & Capability

Name, description, and runtime instructions consistently describe using the swiftfindrefs IndexStoreDB tool to find Swift references. The declared preconditions (macOS, Xcode, DerivedData, swiftfindrefs on PATH) match the stated purpose; no unrelated capabilities or credentials are requested.

Instruction Scope

SKILL.md confines behavior to running swiftfindrefs, interpreting its file-list output, and optionally editing only the returned files (e.g., adding imports). It references DerivedData/IndexStore paths and local file edits — expected for this task. There are no instructions to read unrelated system files, send data to external endpoints, or access secrets.

Install Mechanism

The skill is instruction-only and does not perform an automated install. The README suggests using a brew tap pointing at a third‑party GitHub repo (michaelversus/SwiftFindRefs). That is a plausible install route, but because the tap is third‑party you should inspect the repository or prefer an official release before running brew tap/install.

Credentials

No environment variables, credentials, or config paths are declared or required. The skill implicitly requires filesystem and command execution access (to read DerivedData, run swiftfindrefs, and edit returned source files), which is proportionate to its purpose.

Persistence & Privilege

The skill is not forced always-on (always: false) and does not request persistent elevated privileges or modify other skills. Model invocation is allowed (the platform default) and appropriate for a user-invocable tooling skill.

Assessment

This skill is coherent and appears to do what it says: run the swiftfindrefs tool and act only on the files it reports. Before installing or running anything: (1) verify the swiftfindrefs binary source (the SKILL suggests a third‑party brew tap on GitHub) — review that repository and its releases; (2) run swiftfindrefs manually on a small project to confirm output; (3) be aware the agent will need local filesystem and command execution rights to read DerivedData and edit source files — grant those only if you trust the tool and environment. If you want extra caution, run the tool yourself and let the agent operate only on its output rather than installing a new binary automatically.

Purpose

Use swiftfindrefs to locate every Swift source file that references a given symbol by querying Xcode’s IndexStore (DerivedData). This skill exists to prevent incomplete refactors caused by text search or heuristics.

Rules

• Always run swiftfindrefs before editing any files.
• Only edit files returned by swiftfindrefs.
• Do not substitute grep, rg, IDE search, or filesystem heuristics for reference discovery.
• Do not expand the file set manually.
• If IndexStore/DerivedData resolution fails, stop and report the error. Do not guess.

Preconditions

• macOS with Xcode installed
• Project has been built at least once (DerivedData exists)
• swiftfindrefs available in PATH

Installation

brew tap michaelversus/SwiftFindRefs https://github.com/michaelversus/SwiftFindRefs.git
brew install swiftfindrefs

Canonical command

Prefer providing --projectName and --symbolType when possible.

swiftfindrefs \
  --projectName <XcodeProjectName> \
  --symbolName <SymbolName> \
  --symbolType <class|struct|enum|protocol|function|variable>

Optional flags:

• --dataStorePath <path>: explicit DataStore (or IndexStoreDB) path; skips discovery
• -v, --verbose: enables verbose output for diagnostic purposes (flag, no value required)

Output contract

• One absolute file path per line
• Deduplicated
• Script-friendly (safe to pipe line-by-line)
• Ordering is not semantically meaningful

Standard workflows

Workflow A: Find all references

1. Run swiftfindrefs for the symbol.
2. Treat the output as the complete reference set.
3. If more detail is needed, open only the returned files.

Workflow B: Fix missing imports after moving a symbol

Use swiftfindrefs to restrict scope, then add imports only where needed.

swiftfindrefs -p <Project> -n <Symbol> -t <Type> | while read file; do
  if ! grep -q "^import <ModuleName>$" "$file"; then
    echo "$file"
  fi
done

Then for each printed file:

• Insert import <ModuleName> in the imports block at the top.
• Preserve existing import ordering/grouping.
• Never add duplicate imports.
• Do not reformat unrelated code.

Workflow C: Audit usage before deleting or renaming a symbol

1. Run swiftfindrefs for the symbol.
2. If output is empty, treat the symbol as unused (still validate via build/tests if needed).
3. If non-empty, review the listed files before changing public API.

References

• CLI details: references/cli.md
• Playbooks: references/workflows.md
• Troubleshooting: references/troubleshooting.md