SKILL.md
Type Safety
This project's TypeScript policy. Apply when writing or reviewing TypeScript.
| Rule | Summary |
|---|---|
No as casts |
Every as is a potential runtime crash. Validate at boundaries, then cast only if earned. Prefer Zod/Valibot over manual validation. |
unknown over any |
any disables type checking for everything it touches. External data is always unknown. |
| Discriminated unions | Model variants with a shared literal discriminant. No optional-field bags. |
| Narrowing hierarchy | Prefer: discriminated union switch > in operator > typeof/instanceof > type guard > as |
| Type guards | Must actually verify the claim. Name them isX or hasX. Prefer discriminant narrowing when possible. |
| Exhaustiveness checks | Always add default: never arm to switches over discriminated unions. Use an absurd() helper to reduce boilerplate. |
satisfies over as |
When verifying a value matches a type without widening, use satisfies to preserve literal types. |
| Impossible states | If a bug requires asking "can this combination happen?" the type is too loose. Tighten it. |
Read [references/patterns.md](references/patterns.md) for code examples of each rule.