petekp/seam-ripper

Seam Ripper

Systematically dissect a codebase's internal architecture to expose where it's wrong and propose what's right.

Principles

No sacred cows. Existing patterns are evidence of past decisions, not correct ones.

Seams reveal truth. How components connect exposes what the system actually is, not what documentation claims.

Backwards compatibility is not a constraint. The goal is correct architecture. Migration is a separate problem.

Complexity is guilt until proven innocent. Every abstraction, indirection, and interface must justify its existence.

Execution

Phase 1: Map the Terrain

Build a complete picture of the system's internal structure before judging it.

1. Identify all modules/packages/namespaces - List every bounded unit of code
2. Trace import/dependency graphs - What depends on what, and why
3. Catalog public interfaces - Every exported function, class, type, constant
4. Find the data contracts - Shared types, DTOs, schemas that cross boundaries
5. Locate the integration points - Where modules actually talk to each other

Output a dependency map showing:

• Module → Module edges with dependency reason
• Circular dependencies (immediate red flags)
• Fan-in/fan-out counts per module

Phase 2: Interrogate Each Seam

For every boundary identified, answer these questions:

Interface Clarity

• Can you understand what this module does from its public interface alone?
• Are there "util" or "helper" exports? (smell: no clear responsibility)
• Does the interface expose implementation details?

Dependency Direction

• Does this dependency make conceptual sense?
• Is a "lower-level" module depending on a "higher-level" one?
• Would inverting this dependency simplify both sides?

Coupling Assessment

• How many other modules break if this interface changes?
• Is the coupling through data, behavior, or both?
• Could this be an event/message instead of a direct call?

Abstraction Integrity

• Does this interface leak implementation details?
• Are callers doing work that belongs inside the module?
• Are there multiple ways to accomplish the same thing?

Contract Stability

• How often has this interface changed historically?
• Are there versioned interfaces or deprecation warnings? (smell: unstable contract)
• Do tests mock this interface? (evidence of coupling pain)

Phase 3: Identify Patterns of Failure

Look for these systemic problems:

| Pattern | Symptoms | What's Actually Wrong | |---------|----------|----------------------| | God Module | Everything imports it, huge public API | Missing domain boundaries | | Shotgun Surgery | One change requires edits across many modules | Responsibility scattered | | Feature Envy | Module A constantly reaches into Module B's data | Wrong ownership of data/behavior | | Inappropriate Intimacy | Two modules share private details | Should be one module or have explicit contract | | Middle Man | Module just delegates to another | Unnecessary indirection | | Parallel Hierarchies | Adding X requires adding Y in another module | Missing abstraction | | Speculative Generality | Interfaces for flexibility never used | Premature abstraction | | Dead Abstraction | Interface with one implementation forever | Abstraction without purpose |

Phase 4: Propose the Redesign

For each significant problem, provide:

1. The Indictment State clearly what is wrong and why it matters. Be specific:

• "Module X has 47 public exports and is imported by 23 other modules"
• "The User type is defined in core but has fields only used by billing"

2. The Correct Architecture Describe what it should look like:

• Clear module boundaries with stated responsibilities
• Dependency direction that follows conceptual hierarchy
• Interfaces that expose intent, not implementation

3. The Transformation Concrete steps to get from wrong to right:

• What moves where
• What gets split or merged
• What interfaces change
• What new abstractions emerge

4. The Evidence Explain why this is better:

• Reduced coupling (quantify: N imports → M imports)
• Clearer responsibilities
• Easier to test, extend, or replace

Output Format

# Seam Analysis: [System/Area Name]

## Dependency Map
[Visual or textual representation of module dependencies]

## Critical Findings

### Finding 1: [Problem Name]
**Location:** [modules/files involved]
**Severity:** Critical | High | Medium
**Pattern:** [which failure pattern]

**Evidence:**
[Specific code/structure references]

**Indictment:**
[Clear statement of what's wrong]

**Redesign:**
[Proposed correct architecture]

**Transformation:**
1. [Step]
2. [Step]
...

### Finding 2: ...

## Recommended Architecture

[Overall vision for how the system should be structured]

## Transformation Sequence

[Ordered list of changes, grouped by logical phases]

Red Lines

Refuse to:

• Propose "incremental improvements" that preserve broken architecture
• Accept "but it works" as justification for poor design
• Recommend adapters/facades that hide problems instead of fixing them
• Preserve interfaces just because they're widely used

Always:

• Name the actual problem, not a symptom
• Propose the correct design, not a compromise
• Quantify coupling and complexity where possible
• Explain the conceptual model that makes the redesign correct