Context & Impact Mapping
Map which parts of the system a decision touches before committing, so consequences are visible.
Why
A decision that looks isolated often ripples through caching, observability, deployment, and on-call runbooks. Context & impact mapping forces the author to enumerate every system that the decision touches, which surfaces hidden coupling before it becomes an incident. Teams that skip this step routinely discover, three weeks after adoption, that their new queue broke the deployment pipeline because nobody mapped the impact on the CI config. The map is cheap to draw and expensive to skip.
When
For any decision that crosses a process or team boundary. Takes 15 min. Skip for decisions fully contained in one module with no external interface change.
How
1. List the systems the decision directly changes (e.g. "datastore", "API layer") 2. For each, trace one hop outward: what depends on it? what config does it touch? 3. Draw a simple text diagram: decision → system → downstream effects 4. Mark each effect as + (improves), - (regresses), ~ (neutral) 5. Attach the map to the ADR as an "Impact" section 6. For every '-' effect, add a mitigation line or escalate before accepting
Example
Decision: switch session store from Redis to DynamoDB
Impact map:
decision → session-store
→ API layer: + (no Redis conn pool to manage)
→ deployment: - (new IAM role + table provisioning step)
→ on-call: - (DynamoDB throttling is less debuggable than Redis OOM)
→ cost: ~ (DynamoDB on-demand ≈ Redis small instance at our scale)
→ observability: - (existing Redis dashboards break; need new ones)
Mitigation: add DynamoDB throttling alarm + migration runbook before cutover.Common Problems
- ⚠Mapping only the happy path — the regressions ('-' effects) are exactly the ones that cause incidents, and omitting them defeats the purpose.
- ⚠Drawing the map but not acting on it — a '-' effect with no mitigation is an accepted risk that should be explicit, not silent.
Best Practices
- ✓Keep the map to one screen — if it sprawls, the decision is too broad and should be split into multiple ADRs.
- ✓Review the impact map with the on-call team specifically; they own the '-' effects and must consent.
- ✓Revisit the map 30 days after adoption to verify the predicted effects matched reality — this calibrates future maps.