seams

Seams

The failure mode this fixes

"I can't test this" almost always means "this code has no seams." A seam is a place where you can change behavior without editing the code around it — the joint between deciding what to do and actually doing it. When decision and action are fused (the function fetches, computes, branches on policy, and writes, all in one breath), every test needs a database, every change risks five behaviors, and the logic you actually care about is impossible to isolate.

Agents fuse decision and action constantly, because it's the shortest path to working code. This skill finds the seam and splits along it: pure decisions you can test with plain inputs, thin actions that just carry out the decision.

When to Use This Skill

• You want to write a unit test but the code demands a live dependency
• A function mixes I/O (network, disk, db) with branching business logic
• A small change ripples into unrelated behaviors
• You're about to extract a function and want it to be testable from birth
• Policy ("when do we refund?") is buried inside mechanics ("how do we call Stripe?")

Don't use when: the code is already a thin pure function or a thin I/O shim. Don't add indirection where there's nothing to separate — that's just ceremony.

Instructions

1. Classify every line as DECISION or ACTION

Read the target and tag each chunk:

• DECISION — computes a result from inputs; no side effects. (validation, branching, calculation, choosing what should happen)
• ACTION — touches the outside world. (read/write db, network calls, file I/O, logging, time, randomness)

The seam is the boundary between them.

2. Pull the decision out as a pure function

Extract the DECISION into a function that:

• Takes everything it needs as explicit arguments (no reaching into globals, db, or clock)
• Returns a description of what should happen, not the act of doing it (e.g. return { action: "refund", cents: 1200 }, don't call Stripe)
• Has zero side effects → testable with plain values, no mocks