Seismograph

Seismograph

"An earthquake's damage isn't determined at the epicenter. It's determined by the geology between the epicenter and everything else — the fault lines, the soil composition, the depth of the bedrock. Code changes work the same way."

What It Does

Before you make a change, Seismograph maps the propagation path — every function, module, test, type, config, and downstream system that will feel the tremor. Not just "what calls this function" (your IDE does that), but:

• What assumptions about this code exist elsewhere?
• What tests validate the current behavior you're about to change?
• What documentation promises the behavior you're about to break?
• What downstream systems depend on the output shape you're about to modify?
• What side effects of this code have become relied upon, even though they weren't intended?

The Seismic Model

Earthquake Anatomy → Change Anatomy

Wave Analysis

P-Waves: Direct Impact

Propagation: Immediate callers, importers, and direct consumers. Speed: Instant. These break at compile/import time. Damage: Usually low — these are caught by static analysis.

ANALYSIS:
├── Every file that imports the changed module
├── Every function that calls the changed function
├── Every type that extends or implements the changed type
├── Every test that directly tests the changed behavior
└── Estimated: files affected, lines potentially impacted

S-Waves: Indirect Impact

Propagation: Second-order dependents. Things that use things that use the changed code. Speed: Slower. These break at runtime or during integration testing. Damage: Medium — often caught by integration tests, if they exist.

ANALYSIS:
├── Transitive importers (A uses B uses Changed)
├── Functions that consume the output of changed functions
├── Systems that read data written by changed code
├── Configurations parsed by changed logic
└── Estimated: propagation depth, weakest intermediary

Surface Waves: Side-Effect Impact

Propagation: Code that depends on the behavior of the changed code without explicitly calling it. Event listeners, database triggers, log parsers, monitoring alerts, cached values, file watchers. Speed: Slowest. These break in production, days or weeks later. Damage: Highest — invisible until they cause an incident.

ANALYSIS:
├── Event subscribers that react to events emitted by changed code
├── Monitoring/alerting rules that pattern-match on changed behavior
├── Cached values computed from changed code's output
├── Database triggers fired by changed code's queries
├── Log parsers/aggregators that expect changed code's log format
├── Downstream services that learned (not contracted) the output shape
└── Estimated: probability of surface-wave damage, detection difficulty

Magnitude Scale

Geological Survey: Pre-Change Analysis

Phase 1: EPICENTER MAPPING
├── Identify exact lines being changed
├── Classify change type:
│   ├── Rename (lowest risk)
│   ├── Signature change (medium risk)
│   ├── Behavioral change (high risk)
│   ├── Removal (highest risk)
│   └── Addition (usually safe, unless overloading existing names)
└── Determine magnitude baseline

Phase 2: WAVE PROPAGATION
├── P-Wave analysis:
│   ├── Static dependency graph traversal
│   ├── Type system impact (what breaks at compile time?)
│   └── Direct test impact (what tests fail?)
├── S-Wave analysis:
│   ├── Transitive dependency traversal (2-3 hops)
│   ├── Data flow tracing (output consumed where?)
│   └── Integration test impact
└── Surface-Wave analysis:
    ├── Event/message subscribers
    ├── Database triggers and views
    ├── Monitoring and alerting rules
    ├── Cache invalidation implications
    └── Log format dependencies

Phase 3: FAULT LINE ASSESSMENT
├── For each wave path, assess intervening architecture:
│   ├── Strong boundaries (typed interfaces, contracts) → wave dampened
│   ├── Weak boundaries (duck typing, convention) → wave amplified
│   ├── No boundary (direct coupling) → wave passes through
│   └── Fault lines (known fragile points) → wave magnified
└── Adjust intensity at each affected location

Phase 4: AFTERSHOCK PREDICTION
├── If you fix the primary breakage, what secondary breaks occur?
├── Which fixes are "safe" (localized) vs "cascading" (cause more waves)?
├── Estimated total change set: original change + all required adaptations
└── Is the total change set larger than the original intention warrants?

Phase 5: SEISMOGRAPH REPORT
├── Magnitude and intensity map
├── Prioritized list of affected locations
├── Recommended change strategy (direct, staged, behind flag)
├── Aftershock forecast
└── Go / staged-rollout / reconsider recommendation

Output Format

╔══════════════════════════════════════════════════════════════╗
║                  SEISMOGRAPH ANALYSIS                       ║
║    Proposed: Rename User.email → User.emailAddress           ║
║    Magnitude: 4.7 (Significant)                             ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  EPICENTER: src/models/user.ts:24                            ║
║                                                              ║
║  P-WAVES (Direct Impact):                                    ║
║  ├── 14 files import User and access .email                  ║
║  ├── 8 tests assert on .email                                ║
║  ├── 2 API serializers include 'email' key                   ║
║  └── Compile-time breakage: YES (TypeScript will catch)      ║
║                                                              ║
║  S-WAVES (Indirect Impact):                                  ║
║  ├── 3 services consume User API response with 'email' field ║
║  ├── 1 webhook payload includes 'email' (external consumers) ║
║  ├── 1 CSV export uses 'email' as column header              ║
║  └── Runtime breakage: LIKELY in downstream services         ║
║                                                              ║
║  SURFACE WAVES (Side-Effect Impact):                         ║
║  ├── Elasticsearch index maps 'email' field → search breaks  ║
║  ├── Monitoring alert matches on "email" in log output       ║
║  ├── 2 Zapier integrations reference 'email' field           ║
║  └── Detection difficulty: HIGH (weeks before discovery)     ║
║                                                              ║
║  AFTERSHOCK FORECAST:                                        ║
║  ├── Fixing the 14 P-wave files triggers 0 new waves ✓      ║
║  ├── Fixing the API serializer triggers 3 client-side breaks ║
║  ├── Fixing the webhook requires partner notification        ║
║  └── Total change set: 24 files + 3 external systems        ║
║                                                              ║
║  FAULT LINES CROSSED: 2                                      ║
║  ├── API boundary (typed but externally consumed)            ║
║  └── Webhook contract (no versioning, external consumers)    ║
║                                                              ║
║  RECOMMENDATION: STAGED ROLLOUT                              ║
║  1. Add emailAddress as alias, keep email (backward compat)  ║
║  2. Migrate internal consumers to emailAddress               ║
║  3. Notify external consumers, add deprecation warning       ║
║  4. Remove email after deprecation period                    ║
╚══════════════════════════════════════════════════════════════╝

When to Invoke

• Before any change to a public interface, API, or shared type
• Before renaming anything that crosses a module boundary
• Before modifying database schemas or wire formats
• Before removing any function, field, or parameter
• When someone says "this should be a simple change" (it never is)
• During PR review to assess whether the change accounts for its full impact

Why It Matters

The #1 source of production incidents isn't bad code — it's changes that propagated further than anyone expected. A "simple rename" that broke a webhook. A "minor optimization" that changed a timing guarantee. A "cleanup refactor" that removed a field a downstream system needed.

Seismograph doesn't prevent changes. It prevents surprises. Because the question is never "should we make this change?" — it's "do we understand what this change will touch?"

Zero external dependencies. Zero API calls. Pure static and historical analysis.