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/cli packages/workspace --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): packages/cli/src/util/handle-attachments.ts:41-45: duck-types sync and awareness because the CLI bundles are user-defined and arbitrary. The 30-line comment block above the helper documents exactly why.