Seam Audit

Diagnostic pass over a codebase's boundaries — not the code inside modules, but the places where modules meet. The output is a map and a flagged list, never a change to the code.

Vocabulary

The skill leans on three definitions. Use them explicitly when reporting:

• Module — a section of code with an interface and an implementation. Granularity is project-dependent: a file with exports, a folder of cohesive files, a published package, or a subsystem. Pick a granularity at the start of the run and hold it constant for the whole audit — mid-run re-classification breaks the diagram.
• Seam — an import edge between modules. A has an outgoing seam to B iff A imports B. B's incoming seam from A is the same edge viewed from the other side. Static import / require / use is the default surface; tricky cases (dynamic imports, DI, framework routing) are covered in references/import-graph-traps.md.
• Hub — a module with many seams. Being a hub is not inherently bad: foundational types and orchestrators are hubs by design. The diagnostic question is whether each hub is intentional.

Scope

• Default: entire repo. Step 1 below decides the module granularity; the user is asked only when the default rules are ambiguous.
• Narrowed: if the user names a specific subtree (e.g. "audit the auth subsystem"), enumerate modules within that subtree. Modules outside the subtree are external — count seams to/from them but don't classify them.
• Monorepos and large repos (>~50 modules at the chosen granularity): ask the user to scope to one package, service, or subsystem before running. A repo-wide topology at file-level granularity is rarely informative.
• Excluded by default: vendored code, generated code, build output, third-party packages, test files (the unit-of-audit is the production module; tests don't count toward incoming seams).
• Too-small input: if there are fewer than ~5 modules at any granularity, this skill is the wrong tool. Suggest a regular code review instead.