principle-type-system-discipline

Files (1)

• SKILL.md

SKILL.md (first lines)

# Type System Discipline

Read [the workflow contract](../../references/workflow-contract.md).

Make the compiler reject impossible states, mismatched primitives, and unhandled variants. Prefer defining errors and special cases out of existence over proliferating handlers. Use language-native tagged unions, exhaustive matching, branded primitives or newtypes where they protect real invariants; avoid type machinery with no practical benefit.

- **Brand semantic primitives.** `UserId` and `OrderId` are strings underneath but should not be interchangeable. Give each its own type, such as a branded intersection in TypeScript or a newtype elsewhere. Validate once at creation, trust the type downstream. If two arguments share a primitive type but mean different things, brand them.
- **External data is untyped until parsed.** RPC payloads, JSON, IPC messages, CLI args, config files, environment variables, database rows. Have a parse function at every boundary that turns unstructured input into the typed model. The **boundary-discipline** principle skill says where to put validation.
- **Derive types from authoritative schemas.** When a protocol buffer, OpenAPI spec, GraphQL schema, database migration, design-token file, or another file owns a shape, derive from it instead of hand-rolling a parallel type. See `correct` for structural enforcement of recurring mistakes.

From matthewyjiang/rho-pstack, MIT.

More from matthewyjiang/rho-pstack