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:

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

For High impact:

Consider: Is this change necessary?
Create migration plan
Consider deprecation period
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:

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

After completion:

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

trace-it

Trace It

When To Activate