Splitting a repo-wide Go util package produces an import cycle; how do you carve it up and name the pieces?

## The situation One package — call it `util` — is imported by every service in the repository. It holds retry logic, a time helper, a redaction function for HTTP headers, some string manipulation and a handful of constants. Nobody can name what it is for, so nobody can refuse an addition, and now it is the most-imported package you own. ## Step one: read the call sites, not the files The unit you are redesigning is the string a caller types, so gather evidence about callers before touching the directory. `go list -deps ./...` gives you the transitive package dependencies of every package in the repository, which tells you the fan-in and, crucially, what the bucket itself depends on — a bucket that imports your domain packages is already the wrong shape. A plain search for the `util.` qualifier tells you which exported symbols are actually live and which are dead weight to delete rather than relocate. ## Step two: group by capability, then name for the call site Group the surviving symbols by the capability a caller wanted when they reached for them, and give each group a package name that makes its call sites read as phrases: - a retry loop becomes `retry`, so callers read `retry.Do(ctx, fn)` - header redaction becomes something owned by the HTTP concern, so callers read `httpx.Redact(h)` - an injectable time source becomes `clock`, so callers read `clock.Now()` Two failure modes to name explicitly in review. The first is renaming rather than carving: `util` becomes `helpers` or `common`, which names a bucket just as much as before, and predictably grows a type called `Common` so that call sites read `common.Common` — the stutter and the missing subject are the same defect seen from two angles. The second is splitting by technical layer (`models`, `adapters`, `internalutil`), which reproduces the bucket in triplicate because a layer name still cannot answer whether a given function belongs. ## Step three: the import cycle, and what it is telling you This is the part that catches teams out. Within a single Go package, all files share one scope: a function in `retry.go` may call one in `timefmt.go` and vice versa, with no declarations, no ordering rules and no visible dependency. The moment those two files become two packages, the same two calls become two imports pointing at each other, and the Go compiler refuses the build outright — the message is `import cycle not allowed`, with the chain of imports printed. Go has no forward declaration and no tolerance for cyclic package imports; this is a hard rule, not a warning. The important framing for a review or a postmortem is that the split did not create the cycle. The mutual dependency was always there, hidden by the fact that both halves lived in one package. The grab bag was concealing a layering defect, and the compiler is now doing you the favour of naming it. The fixes are structural, in rough order of preference: 1. **Push the shared thing down.** If both packages need a type or a constant, put it in a small package that imports nothing from either — a leaf of the graph. Types with no behaviour make excellent leaves. 2. **Move the function to the data.** Very often one of the two halves is simply in the wrong package: the function that formats a `Job` belongs with `Job`. 3. **Invert the direction with a small parameter.** Pass a function value or a narrow interface defined by the consumer so the lower package never has to import the higher one. What you should not do is duplicate the shared type into both packages to break the cycle. Two structurally identical types are distinct types in Go, and you will spend the next year writing conversions between them. ## Step four: migrate without a flag day Move one capability at a time. The old package keeps compiling while it still has symbols; delete each symbol as its new home takes over, and let the build tell you where the stale references are — because every reference is qualified with the package name, the compiler enumerates the complete list of call sites for you, which makes the edit mechanical rather than a search-and-hope. Do not leave a forwarding shim behind "for compatibility" inside a repository you control end to end; a shim keeps the old name alive at exactly the call sites you were trying to fix, and the old name is the problem. ## How to talk about it An interviewer is listening for three things: that you design from the call site, that you understand why the cycle appeared only at the split, and that you treat the cycle as information about layering rather than an obstacle to route around. Mentioning that the deletion pass is compiler-verified — every use is qualified, so nothing hides — is the detail that shows you have actually done one.