Code Audit Patterns

Recurring smell categories worth hunting periodically. Each category has a grep pattern, a real example from the repo (if one exists), and a "why it matters" so you know whether a hit is a real smell or expected.

Related skills: See post-implementation-review for the full second-read ritual after implementation. See refactoring for the methodology of fixing what you find. See one-sentence-test for the cohesion audit that frames whether an abstraction earns its keep.

The categories below were validated against the actual codebase by repeated agent audits. They're not generic style nits: each one signals a specific kind of contract problem in a TypeScript-heavy framework codebase.

1. Duck-Typing at System Boundaries

Pattern: (x as { foo?: unknown }).foo or as Record<string, unknown> accesses where the shape isn't statically known.

grep -rn "as\s*{" packages apps --include="*.ts" -B2 -A2

Why it matters: Each duck-type is a contract gap. The receiver doesn't know what it's getting; the producer doesn't know what's expected. Often justified at literal system boundaries (e.g., parsing user-provided configs, reading from third-party APIs), but unjustified inside the framework's own code.

Example (justified): a loader that duck-types fields off a user-authored module it imports at runtime, because the module's shape is arbitrary by design. What makes it justified is the comment block above the access explaining exactly why static typing is impossible there.