staff-engineering-skills-cardinality
Installation
SKILL.md
Cardinality Trap
Code that works for 10 items becomes a production incident at 10 million. Before writing any code that operates on a collection, ask: how many items can this collection contain, and what controls that number?
The Cardinality Levels
Classify every collection you touch:
| Level | Controlled by | Examples | Safe to load in memory? |
|---|---|---|---|
| L1 | Code (deploy to change) | Enums, feature flags, status codes | Yes |
| L2 | Real-world constraints | Countries, US states, time zones | Yes, but verify count |
| L3 | User action + limits | Team members (capped at 50), projects per workspace | With caution. Limits change. |
| L4 | User action, no limits | Documents, messages, spreadsheet rows | No. Paginate always. |
| L5 | API/automation + time | API requests, log entries, webhook events, metrics | No. Assume millions. Stream or batch. |
The 2nd Degree Rule: Treat L4 as L5. User-driven collections almost always gain API access later. "Documents in a drive" becomes "documents created by an integration every 5 minutes."