change-impact-map skill

---
name: Change Impact Map
description: A practical framework to map change dependencies and blast radius, including who/what is affected, what to test, rollout/rollback strategies, and stakeholder ownership
---

# Change Impact Map

## Overview

Documentation showing "if we change A, what B/C are affected" - dependency relationships between components that help assess change impact before implementation.

## Why This Matters

- **Risk assessment**: Know what breaks after a change
- **Test coverage**: Know what to test
- **Review scope**: Know who needs to review
- **Rollback planning**: Know what to rollback

---

## Core Concepts

### 1. Dependency Types

- **Code deps**: imports, shared modules, shared contracts, shared libraries
- **Runtime deps**: services called, queues/topics, caches, feature flags, config
- **Data deps**: tables/collections, schemas, indexes, migrations, analytics pipelines
- **Integration deps**: third-party APIs, webhooks, auth providers, payment processors

### 2. Impact Categories

- **Direct**: component being changed directly (file/module/service)
- **Indirect**: things that call it/are called by it (upstream/downstream)
- **Operational**: deploy, migrations, observability, on-call/runbooks
- **User-facing**: UX, SLAs/SLOs, billing, security/compliance

### 3. Critical Paths

- Identify P0/P1 paths that if broken affect the entire system (auth, payments, DB connection, routing)
- Connect to existing SLOs and alerts to define "must watch" metrics
- Don't change behavior in critical paths without staged rollout or kill switch

### 4. Change Scopes

- **Small**: single module, isolated behavior → unit tests + targeted smoke
- **Medium**: multiple files, one service → integration tests + staging validation
- **Large**: multi-service or schema/contract change → migration plan + canary + rollback playbook

### 5. Blast Radius

- Ask "if this part goes down, what fails as a domino" (availability / correctness / latency)
- Identify failure modes: timeout, retries storm, stale cache, partial writes, auth failures
- Identify data risk: corruption, duplication, backfill issues, missing events

### 6. Ripple Effects

- Second/third-order impacts: background jobs, reporting, search indexing, notifications
- Changing field/type may impact: SDKs, mobile app, dashboards, data warehouse
- Consider "migration window" where versions run together (old/new running)

### 7. Affected Stakeholders

- owners/reviewers per component (team + on-call)
- consumers of API/events (other teams/partners)
- stakeholders: support, sales, finance, security/compliance (by change type)

### 8. Mitigation Strategies

- **Feature flags** for cutover/kill switch
- **Canary/gradual rollout** to reduce risk and detect early
- **Compatibility**: backward-compatible contracts + deprecation plan
- **Verification**: dashboards, synthetic checks, sampling, shadow reads (if appropriate)

## Quick Start

- Identify "change surface": files/modules/services/tables/events touched
- Do dependency sweep: code imports + runtime calls + data + integrations
- Fill impact matrix (direct/indirect + must test)
- Add mitigation: feature flag/canary/rollback + metrics to watch
- Identify owners/reviewers and communicate with stakeholders before merge/deploy

## Production Checklist

- [ ] Critical paths documented
- [ ] Dependencies mapped
- [ ] Impact matrix created
- [ ] Stakeholders identified
- [ ] Updated on architecture changes
- [ ] Used in change management

## Change Impact Map Template

````markdown
# IMPACT_MAP.md

> Last updated: 2024-01-15

## High-Level Dependencies

```
┌─────────────────────────────────────────────────────┐
│                    Frontend                          │
│  (React App, Mobile App)                            │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│                   API Gateway                        │
│  (Auth, Rate Limiting, Routing)                     │
└──────┬─────────────┬─────────────┬──────────────────┘
       │             │             │
       ▼             ▼             ▼
┌──────────┐   ┌──────────┐   ┌──────────┐
│  User    │   │  Order   │   │  Payment │
│  Service │   │  Service │   │  Service │
└────┬─────┘   └────┬─────┘   └────┬─────┘
     │              │              │
     └──────────────┼──────────────┘
                    ▼
          ┌──────────────────┐
          │    PostgreSQL    │
          │    Redis Cache   │
          └──────────────────┘
```

## Component Impact Matrix

| If you change... | Direct Impact | Indirect Impact | Must Test |
|------------------|---------------|-----------------|-----------|
| User Service | Auth flow | All services (auth tokens) | Login, Registration, All API calls |
| Order Service | Order creation | Payment processing, Notifications | Create order, Payment flow |
| Payment Service | Checkout | Order completion, Receipts | Full checkout flow |
| Database Schema | All services | N/A | All integration tests |
| API Gateway Config | All routes | Frontend apps | Smoke tests |

## Critical Path Analysis

### 🔴 Critical (P0 Impact)
Changes here can cause total outage:
- `src/infrastructure/db/connection.ts` - Database connection
- `src/middleware/auth.ts` - Authentication
- `src/api/gateway/routes.ts` - API routing
- `config/production.ts` - Production config

**Required**: Full test suite, staged rollout, immediate rollback plan

### 🟠 High Impact (P1)
Changes here affect major features:
- `src/domain/users/` - User management
- `src/domain/orders/` - Order processing
- `src/domain/payments/` - Payment handling

**Required**: Integration tests, canary deployment

### 🟡 Medium Impact (P2)
Changes here affect specific features:
- `src/domain/notifications/` - Email/SMS
- `src/domain/reports/` - Reporting
- `src/api/admin/` - Admin functions

**Required**: Unit tests, feature flag

### 🟢 Low Impact (P3)
Changes here are isolated:
- `src/shared/utils/` - Utility functions
- `src/shared/constants/` - Constants
- Documentation files

**Required**: Unit tests

## Dependency Chains

### User Authentication
```
Change: src/domain/users/auth/
Impact chain:
1. User Service (login/logout)
   ↓
2. API Gateway (token validation)
   ↓
3. All Services (auth middleware)
   ↓
4. Frontend (auth state)
   ↓
5. Mobile App (auth state)
```

### Database Schema
```
Change: prisma/schema.prisma
Impact chain:
1. Database migration required
   ↓
2. All repositories using changed tables
   ↓
3. All services using those repositories
   ↓
4. API responses may change
   ↓
5. Frontend/Mobile display
```

### Shared Types
```
Change: src/shared/types/user.ts
Impact chain:
1. All files importing User type
   ↓
2. API request/response shapes
   ↓
3. Frontend type definitions
   ↓
4. Test mocks and fixtures
```

## Team Ownership

| Component | Owner | Reviewer |
|-----------|-------|----------|
| User Service | @auth-team | @security-team |
| Order Service | @commerce-team | @backend-lead |
| Payment Service | @payments-team | @security-team, @finance |
| Infrastructure | @platform-team | @sre |
| Database | @data-team | @backend-lead |
| Frontend | @frontend-team | @ux-team |

## Change Checklist by Scope

### Small Change (Single file, isolated)
- [ ] Unit tests pass
- [ ] Code review by 1 person
- [ ] Deploy to staging
- [ ] Quick smoke test

### Medium Change (Multiple files, one service)
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Code review by 2 people
- [ ] Deploy to staging
- [ ] Full feature test
- [ ] Monitor for 30 min

### Large Change (Multiple services, schema change)
- [ ] All tests pass
- [ ] Security review (if auth/data)
- [ ] Code review by team lead
- [ ] Database migration reviewed
- [ ] Feature flag ready
- [ ] Rollback plan documented
- [ ] Canary deployment
- [ ] Monitor for 24 hours
````

## Impact Assessment Questions

```markdown
Before making a change, answer:

1. **What depends on this?**
   - Which files import this?
   - Which services call this?
   - Which tests cover this?

2. **What does this depend on?**
   - External APIs?
   - Database tables?
   - Configuration?

3. **Who needs to know?**
   - Which teams?
   - Which stakeholders?
   - Which customers?

4. **What could go wrong?**
   - Failure modes?
   - Edge cases?
   - Data corruption?

5. **How do we verify success?**
   - Tests to run?
   - Metrics to watch?
   - Manual checks?
```
````

## Anti-patterns

1. **No impact assessment**: "It's just a small change"
2. **Missing dependencies**: Hidden coupling
3. **Outdated map**: Doesn't reflect current architecture
4. **No ownership**: No one responsible for areas

## Integration Points

- Change management process
- Code review templates
- CI/CD pipelines
- Incident post-mortems

## Further Reading

- [Dependency Mapping](https://martinfowler.com/bliki/Strangler.html)
- [Change Management](https://www.atlassian.com/itsm/change-management)