Refactor Check

---
name: refactor-check
description: Safety analysis before refactoring -- dependency graph, test coverage, public API exposure, blast radius verdict.
argument-hint: "<function or class name> [intended change]"
---

# Refactor Check

Analyze whether a refactoring is safe BEFORE making changes. Produces a verdict with specific risks and mitigation steps.

**Command surface:** run the local CLI through the coding harness shell. Examples
use the installed `crg` command; from a source checkout,
prefix it with `uv run`. No MCP mapping is required.

## Steps

1. **Get the full dependency graph** for the target:
   - `crg graph build --base HEAD --repo-root "<path>"` to index current working changes
   - `crg query query --pattern callers_of --target "<name>" --repo-root "<path>"` -- who calls this
   - use `--pattern callees_of` to see what this calls
   - use `--pattern imports_of` to see what this imports
   - If it is a class, also query `--pattern inheritors_of` and `--pattern children_of`

2. **Identify test coverage**:
   - `crg query query --pattern tests_for --target "<name>" --repo-root "<path>"` -- direct tests
   - For each caller, also query `tests_for` to see if callers have integration tests covering this function indirectly
   - Record: number of direct tests, number of callers with tests, number of callers without tests

3. **Flag public API exposure**:
   - Check if the target is exported from a package `__init__.py`, `index.ts`, or similar
   - Check if the target is referenced from outside its own module/package
   - Check if the target appears in documentation or type stubs
   - Public API = any function/class importable by external consumers

4. **Estimate blast radius**:
   - `crg query impact --changed-files "<target-file>" --repo-root "<path>"` -- file-level impact analysis around the target
   - Count: total impacted files, total impacted functions, depth of dependency chain
   - Identify any impacted files outside the immediate package/module

5. **Produce verdict**:

   ```
   ## Refactor Safety: <name>

   ### Target
   - **Location**: <file_path>:<line>
   - **Type**: function / class / method
   - **Public API**: Yes / No

   ### Dependency Summary
   - **Callers**: N functions depend on this
   - **Callees**: Calls M other functions
   - **Inheritance**: N subclasses (if class)

   ### Test Coverage
   - **Direct tests**: N tests
   - **Caller tests**: M/K callers have tests covering this path
   - **Coverage gaps**: <list uncovered callers>

   ### Blast Radius
   - **Impacted files**: N
   - **Impacted functions**: M
   - **Max depth**: K hops

   ### Verdict: SAFE / NEEDS MIGRATION / DANGEROUS

   **SAFE** -- Low blast radius (<5 files), good test coverage, no public API exposure.
   Make the change, run tests, done.

   **NEEDS MIGRATION** -- Public API or moderate blast radius (5-15 files).
   Recommended approach:
   1. Create new version alongside old
   2. Migrate callers incrementally
   3. Deprecate old version
   4. Remove after all callers migrated

   **DANGEROUS** -- High blast radius (>15 files), poor test coverage, or public API with external consumers.
   Specific risks:
   - <risk 1 with affected files>
   - <risk 2 with affected files>
   Mitigation: <steps to reduce risk before proceeding>
   ```

## Verdict Criteria

| Condition | Verdict |
|---|---|
| <5 impacted files, not public API, >80% caller test coverage | SAFE |
| 5-15 impacted files OR public API with known consumers | NEEDS MIGRATION |
| >15 impacted files OR public API with unknown consumers OR <50% test coverage | DANGEROUS |
| Any external package/library depends on it | DANGEROUS |

## When to Use

- Before renaming a function, class, or method
- Before changing a function signature (parameters, return type)
- Before moving code to a different module/package
- Before splitting a class or merging functions
- Before deleting code that might still be referenced