Code Blast Radius

Important

This skill runs BEFORE any code changes. Its only job is to map impact so you can decide whether the refactor is safe to proceed. It never modifies files. If the blast radius is HIGH, it stops and reports — it does not attempt to fix anything. Always run this before renaming, moving, or restructuring any module, class, or function that other code depends on.

Instructions

1. Identify the target. Confirm with the user exactly what is being refactored: a function name, class name, file path, or module. If ambiguous, ask before proceeding.

2. Find all direct references. Search the codebase for every location that imports, calls, or instantiates the target. Use Grep with appropriate patterns:

   • For functions: search for the function name as a call site (target_name(, .target_name()
   • For classes: search for import statements, inheritance (class Foo(Target)), and instantiation (Target()
   • For files/modules: search for import paths (from path.to.module import, require('path/to/module'), import 'path/to/module')
   • For TypeScript/JavaScript: also check re-exports (export { ... } from)

3. Find all indirect references. For each direct caller found in step 2, check whether that caller is itself exported or re-exported. This surfaces second-order blast radius. Limit to two hops to avoid unbounded recursion — flag if deeper chains exist.

4. Categorize findings by type:

   • Callers — functions/methods that call the target directly
   • Importers — files that import the target (may or may not use it)
   • Inheritors — classes that extend or implement the target
   • Re-exporters — modules that re-export the target to other consumers
   • Test files — test files that reference the target (separate category — tests break silently)

5. Score blast radius.

   • LOW — 1-3 files, no re-exports, no inheritance, target is internal/private
   • MEDIUM — 4-10 files, or any re-export, or used across 2+ top-level directories
   • HIGH — 11+ files, or public API surface, or re-exported, or inherited by multiple classes, or used in test fixtures/mocks

6. Flag high-risk patterns. Specifically call out:

   • Files in node_modules or third-party code that reference the target (rare but critical)
   • Dynamic references: string-based imports, require(variable), getattr(obj, name) — these cannot be found by static search and must be flagged as undetectable risk
   • Missing test coverage for callers (callers with no corresponding test file)
   • Cross-package usage (monorepos where the target is imported by a different package)

7. Output a structured report.

   ## Refactor Radar — [target name]
   
   Blast Radius: [LOW / MEDIUM / HIGH]
   
   ### Direct References ([count] files)
   - path/to/caller.ts — [type: caller / importer / inheritor]
   - ...
   
   ### Indirect References ([count] files, 2-hop)
   - path/to/indirect.ts — via [intermediate file]
   - ...
   
   ### Test Coverage
   - [file] — covered by [test file] / UNCOVERED
   - ...
   
   ### High-Risk Flags
   - [flag description] — [file or pattern]
   
   ### Recommendation
   [Safe to proceed / Proceed with caution — update N files / High risk — review before changing]
   

8. Stop if HIGH. When blast radius is HIGH, end the report with a clear recommendation to review the full list before making any changes. Do not begin refactoring. Let the user decide.

Error Handling

• Target not found in codebase: Report "No references found for [target]. Either the name is misspelled, it is unused (dead code), or it is referenced only through dynamic patterns." Do not proceed.
• Ambiguous target name (common word): Warn the user that the search term is generic and results may include false positives. List the top matches and ask for confirmation of which one is the intended target before scoring blast radius.
• Binary/generated files in results: Exclude dist/, build/, .next/, __pycache__/, and other generated directories from the scan. Note that generated files were excluded.
• Monorepo with many packages: Note that the scan covers the local workspace. If the target is published as an npm/pip package consumed externally, external consumers cannot be detected.

Examples

Example 1 — Low blast radius User: "I want to rename formatDate in src/utils/dates.ts. Is it safe?" Skill finds 2 callers in src/components/, 1 test file. No re-exports, no inheritance. Output: Blast Radius LOW. 3 files need updating. Safe to proceed.

Example 2 — High blast radius User: "Blast radius on moving ApiClient class out of src/api/client.ts" Skill finds 14 direct importers across 4 packages, 3 classes that extend it, 2 re-export files. Output: Blast Radius HIGH. 19 files affected. Flags 3 uncovered callers and 1 dynamic require(). Recommendation: review full list before changing.

Example 3 — Dynamic reference warning User: "What depends on get_model in models/registry.py?" Skill finds 5 static callers, but also detects getattr(registry, model_name) patterns in 2 files. Output: Blast Radius MEDIUM (5 static) + flags 2 files with undetectable dynamic references.