/pstack:typescript-best-practices
Call when neededIn one lineTurns the type principles into concrete TypeScript habits, like handling every possible case.
- When to use
- The task touches .ts / .tsx files. It doesn't load on its own; you have to name it.
/pstack:typescript-best-practicesJust asking vs. using it
The same request, typed plainly or with /pstack:typescript-best-practices. Here's what changes.
With /pstack:typescript-best-practicesas so the code compiles.Validates data where it enters, and casts only after that check.kind literal so impossible states can't exist.any.Types outside data as unknown and parses it with the repo's schema library.What the document says
About 350 words, 2 min to read.
OpeningIt applies the type-system-discipline principle first, then gives a 16-rule table, from kind unions and unknown for outside data to real tests and no console.log in shipped code. Examples live in references/patterns.md.
Wording worth borrowing
A few sentences from the original: what each one makes the AI do, why it works, and how you can borrow it.
Point to the principle first
Apply the type-system-discipline principle skill first.
- Makes the AI
- It thinks with the general type principles first, then applies the TypeScript rules, so cases the table misses still have a guide.
- Why it works
- A rule list is never complete; one opening line naming the principle behind it tells the AI which way to lean off the list.
- Borrow it
- Before a list of specifics, give the aim: 'The goal is that older users get it at a glance; for example big text, few buttons, no English.'
Rank the options in one line
Discriminant switch >
inoperator >typeof/instanceof> user-defined type guard >as.- Makes the AI
- When it must tell types apart it starts from the safest method and keeps
asas a last resort. - Why it works
- A chain of ">" lines the choices up, so the AI sees which to try first and which is worst, without a paragraph each.
- Borrow it
- With several ways to do something, rank them: "Official docs > GitHub issues > blog posts."
Expose the fake improvement
A lying guard is worse than
asbecause the bug hides behind a name that says it's safe.- Makes the AI
- Its
isXfunctions really check each field, instead of a nicely named shell that checks nothing. - Why it works
- AIs take a more formal form as progress; saying why it's more dangerous blocks compliance in name only.
- Borrow it
- Where form can replace substance, call it out: "An empty try/catch is worse than none, because it hides the error."
Put the exception beside the rule
Skip on hot paths (per-frame render, tokenizers, parsers).
- Makes the AI
- It passes objects by default, but won't slow down code that runs every frame just to follow the rule.
- Why it works
- With the exception in the same cell and concrete cases named, the AI neither over-applies the rule nor stretches the exception.
- Borrow it
- When you set a rule, add the exception: "Reply in Chinese, but keep error messages and commands in English."
Full text
The SKILL.md the AI reads, as written.
descriptionTypeScript best practices. Use when reading or editing any .ts or .tsx file.
TypeScript best practices
Apply the type-system-discipline principle skill first.
| Rule | Summary |
|---|---|
| Discriminated unions | Model variants with a kind literal discriminant so impossible states can't be represented. No optional-field bags. |
| Branded types | Brand primitives with & { readonly __brand: "X" } so they can't be mixed up. Validate once at the boundary. A brand comes from a verifying type guard (input is AgentId), never from as. |
| Constructive modeling | Build the shape so the illegal value can't be constructed. [T, ...T[]] for non-empty, [T, T][] for even length, start plus duration for a range. Not a runtime guard, not a wish for refinement types. |
| Simplest total type | Keep T[] while every operation on it stays total. Strengthen to NonEmpty<T> only where the loose type forces !, a cast, or a "should never happen" throw. |
unknown over any |
External data is unknown. |
| Schemas before guards | Before hand-writing a property-by-property type guard, use the repository's runtime schema library and infer the type from the schema, such as z.infer. |
No as casts |
Every as is a runtime crash waiting. Cast only after validation. |
| Narrowing hierarchy | Discriminant switch > in operator > typeof/instanceof > user-defined type guard > as. |
| Type guards | Must verify the claim. A lying guard is worse than as because the bug hides behind a name that says it's safe. Name them isX or hasX. |
| Exhaustiveness | Inline const _exhaustive: never = x; in default arms so the compiler errors when a new variant is added. |
satisfies over as |
Validates the value without widening literal types. |
| Boundary validation | Parse where data crosses in, into a named domain type. Record<string, unknown> (however spelled) stops at that parse. Trust types inside. See the boundary-discipline principle skill. |
| Schema-derived types | Reach for Pick/Omit/Parameters/ReturnType/Awaited/typeof before declaring a new interface. |
| Object args | Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers). |
| Real tests | Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally. |
| Structured telemetry | Prefer structured logger diagnostics with enough context to debug from an id. No console.log in shipped code. |
Examples: references/patterns.md.
Original by Lauren Tan (poteto), MIT license. Checked against the pstack mirror at 97de40d. View on GitHub