develop-write

name	develop-write
description	Writes idiomatic, type-safe code - precise modeling, narrowing, boundary validation. Loads a stack reference (e.g. typescript). Use when writing or modifying source, not tidying (develop-clean).
argument-hint	<stack>

Writing idiomatic, type-safe code

Write code the type checker can prove correct: model state so illegal combinations cannot be expressed, narrow values instead of asserting them, and ban the escape hatches that hide bugs. Follow dev-principles - the least code, leaning on built-in language features before reaching for libraries.

Use when authoring or refactoring source in any language. For toolchain and strictness setup see develop-configure; for migrating existing code to stricter types see develop-maintain; for packaging a library see develop-publish.

Stack guidance

Load references/typescript.md for the target language's concrete syntax (add more stacks as reference files); with no file for the user's language, apply the guidance below and say so.

Core principles

• Make illegal states unrepresentable. A sum / tagged-union / enum of valid shapes beats a wide record of optional fields plus runtime guards. If a combination must never occur, the type should forbid it.
• Pick the most precise type; avoid escape hatches. Every unchecked cast, force-unwrap, or any-equivalent is an unproven claim that spreads silently. Prefer an unknown-equivalent at the edge and narrow before use.
• Narrow, do not assert. Replace casts with checks the checker understands - tag switches, type predicates, validators. The compiler should follow your reasoning, not be told to trust it.
• Infer where correct, annotate at boundaries. Let inference carry local code; annotate parameters, public return types, and exported boundaries so APIs stay stable and errors land where the mistake is.
• One source of truth per type. Derive related types from a base (utility / derived types, generics) instead of restating shapes that then drift apart.
• Exhaustiveness. When branching on a finite set of variants, make a missed case a compile error (a never-equivalent), so adding a variant forces handling it everywhere.
• Nominal distinctions where structure would merge them. Give UserId vs OrderId, a validated Email, or units a distinct identity (branded / newtype / opaque), constructed through one validating factory.

Validation at boundaries

• Data crossing a runtime boundary (network, disk, env, deserialization) is untrusted and untyped. Validate its shape before the rest of the code trusts it.
• Prefer the language's own checks or a small schema validator over blind casts. Per dev-principles, do not add a dependency for a single boundary a hand-written guard already covers.

Gotchas

• A cast or force-unwrap that "makes the error go away" usually moves a real bug downstream; treat each as a TODO to narrow.
• Deep type-level cleverness (elaborate generic or type-level computation) hurts readability and checker speed - reach for a named helper or a plainer type first.
• "Compiles" is not "correct at the boundary": types describe in-process values, not the bytes arriving from outside. Validate.
• An ever-growing pile of optional fields is a smell that the state should be split into distinct variants.