trace-it

name	trace-it
description	Before modifying shared code (utilities, types, configs, base classes), traces all callers and dependents first. Activates when editing files in shared/, utils/, lib/, or anything imported by 3+ files. Prevents "fixed one thing, broke three others."
allowed-tools	bash: grep, find, git file: read

Trace It

Shared code is high-leverage but high-risk. Change a utility function and you might break 10 callers. Change a type definition and you invalidate assumptions across the codebase. This skill forces you to trace impact before editing.

When To Activate

- Editing files in: `utils/`, `lib/`, `shared/`, `common/`, `core/` - Modifying exported functions, classes, or types - Changing function signatures (parameters, return types) - Editing config files or constants - Renaming anything that might be imported elsewhere - Modifying base classes or interfaces - User says "change how X works" for foundational code

Instructions

Before Modifying Shared Code

<trace_callers>

Step 1: Find All Callers

# Find imports/requires of this file
grep -r "from.*['\"].*filename" src/
grep -r "import.*filename" src/
grep -r "require.*filename" src/

# Find usages of specific function/class
grep -r "functionName" src/ --include="*.ts"

Document what you find:

## Dependency Trace: [file or function name]

**Direct callers:** [count]
- `src/api/handler.ts:23` - uses for validation
- `src/services/user.ts:45` - uses for formatting
- `src/utils/helpers.ts:12` - re-exports it

**Indirect dependents:** [count]
- Files that import the direct callers

</trace_callers>

<assess_impact>

Step 2: Assess Impact

For each caller, determine:

Caller	How it uses this	Will change break it?
handler.ts	Calls validate(input)	Yes - signature changes
user.ts	Uses return value	No - return type same

Impact level:

• Low: 1-2 callers, simple usages
• Medium: 3-5 callers, varied usages
• High: 6+ callers OR complex/varied usages </assess_impact>

<plan_migration>

Step 3: Plan the Change

For Low impact: Proceed, update callers inline.

For Medium impact:

1. Make change backward-compatible if possible
2. Update all callers in same commit
3. Test each caller's behavior

For High impact:

1. Consider: Is this change necessary?
2. Create migration plan
3. Consider deprecation period
4. Update incrementally with tests </plan_migration>

Signature Changes

When changing function signatures:

## Signature Change

**Before:** `function process(data: string): Result`
**After:** `function process(data: string, options?: Options): Result`

**Breaking:** No (new param is optional)
**Callers to update:** 0 required, 5 could benefit

## OR

**Before:** `function process(data: string): Result`
**After:** `function process(data: ProcessInput): Result`

**Breaking:** Yes
**Callers to update:** 8 files
**Migration:** [list each file and required change]

Output Format

## Trace: [what you're changing]

**Callers found:** [count]
**Impact level:** [Low/Medium/High]

**Changes required:**
- [ ] `file1.ts:line` - [what needs updating]
- [ ] `file2.ts:line` - [what needs updating]

**Verified after change:**
- [ ] All callers updated
- [ ] No new type errors
- [ ] Tests pass

NEVER

• Modify shared code without tracing callers first
• Change function signatures assuming "it's probably fine"
• Update shared code and only test one caller
• Forget to check re-exports (file A exports from file B)
• Assume grep found everything (check for dynamic imports)

ALWAYS

• Trace before touching shared code
• Document the caller count and impact level
• Update ALL callers in the same change
• Verify no type errors after the change
• Check for string-based references (dynamic imports, configs)

Example

User: "Rename the formatDate function to formatDateTime"

Trace:

grep -r "formatDate" src/

Found:

src/utils/date.ts:15 - definition
src/components/Header.tsx:8 - import
src/components/EventCard.tsx:12 - import
src/pages/Dashboard.tsx:45 - import
src/api/events.ts:23 - import
src/utils/index.ts:5 - re-export

Impact: 6 files reference this. High impact.

Plan:

1. Rename in date.ts
2. Update re-export in utils/index.ts
3. Update imports in all 4 consumer files
4. Verify: grep -r "formatDate" src/ returns nothing

After completion:

Renamed formatDate → formatDateTime across 6 files. Verified: no remaining references to old name.