---
name: impact-analysis
description: Analyze the impact scope when modifying logic or the database to ensure system-wide safety.
keywords: impact, refactor, breaking change, scope
---

# Impact Analysis

## When mandatory to run

- Modifying **Core Services / shared utilities** used in many places
- Changing **database schema** (add/rename/drop column, table)
- Changing **API response structure** (rename field, remove field)
- Changing **interfaces / contracts** between modules
- After fixing a bug — to ensure the fix doesn't break other parts

---

## Analysis Process

### Step 1: Find all usage (Dependency Map)

**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
```
impact("ClassName")    → structured blast radius: callers, dependents, risk score
detect_changes()       → reads current git diff, maps changed lines → affected symbols
```
- Use `impact()` when you know the class/function name being modified.
- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
- One call replaces all grep commands below. Proceed directly to Step 2 with the result.

**Fallback — grep manually** (if GitNexus not configured):
```bash
# Find all files importing/calling the class/function being modified
grep -r "ClassName\|functionName\|methodName" --include="*.php" .
grep -r "ClassName\|functionName\|methodName" --include="*.java" .
grep -r "ClassName\|functionName\|methodName" --include="*.ts" .

# Check which routes/controllers trigger this service
grep -r "ServiceName" app/Http/Controllers/
```

List all:
- Controllers / Routes calling it directly
- Jobs / Commands / Events calling it indirectly
- Tests mocking/stubbing this class
- Frontend components calling related APIs

### Step 2: Evaluate each aspect

| Aspect | Checkpoint questions |
|-----------|---------------------|
| **Database / Cache** | Which queries are affected by schema changes? Which cache keys need flushing? |
| **Background Jobs** | Which Crons / Queues call this logic? Will they break? |
| **Import / Export** | Do bulk data flows use this field/logic? |
| **Permissions** | Are API / UI permission checks sufficient after the change? |
| **API / Mobile** | Will JSON responses lose fields? Do mobile clients need updates? |
| **Tests** | Which tests will fail? Which mocks/stubs need updating? |

### Step 3: Classify impact level

| Level | Definition | Action |
|-----|-----------|-----------|
| 🟢 Low | Only 1 file, no dependencies | Proceed |
| 🟡 Medium | 2–5 files, tests need updates | Review carefully before merging |
| 🔴 High | 6+ files, API breaking change, DB migration | Discuss with the team first |
| ⛔ Critical | Affects payment, auth, data integrity | Tech Lead review mandatory |

### Step 4: Export report

**Report structure:**

```
## Impact Analysis: [Change Name]

**Level:** 🟡 Medium

### Impact Scope
- [File/Class A] — [reason for impact]
- [File/Class B] — [reason for impact]

### Breaking changes
- [Describe breaking change if any]

### Tests to check after merge
- [ ] [Test case / screen 1]
- [ ] [Test case / screen 2]
- [ ] [Job/Command to test run]

### Notes for QA
[Specific points QA should pay attention to]
```

Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).

---

## Completion Checklist

- [ ] Found all dependencies using grep/IDE search
- [ ] Checked Jobs, Events, and Crons
- [ ] Checked API response structure
- [ ] Checked tests
- [ ] Determined impact level (Low/Medium/High/Critical)
- [ ] Wrote impact report
- [ ] Notified the team if High/Critical