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**
- Do