coding-effectively

name	coding-effectively
description	Always use this skill when writing or refactoring code. Covers general code design, error handling, file organization, and code style patterns.
cc:user-invocable	false

Coding Effectively

Correctness over convenience

Model the full error space, not the path you had in mind. Handle every edge case — race conditions, timing issues, partial failures. Encode constraints in the type system, and prefer compile-time guarantees to runtime checks. Never bypass the type system to silence a compiler error (as any, unchecked casts). When uncertain, explore and iterate rather than assume.

Error handling

Never swallow an error. Every error is one of three things:

• Recoverable locally — handle it
• Unrecoverable locally — pass it up the stack
• Non-critical — log it, increment a metric, or both

Two tiers: user-facing errors get semantic exit codes, rich diagnostics, and actionable messages. Internal errors are programming errors, and may panic or use internal types. Never emit a generic message where the specific cause is known.

Message format — lowercase sentence fragments, so that "operation failed: " + error.message composes:

Good: failed to connect to database: connection refused
Bad:  Failed to Connect to Database: Connection Refused

Design

• Don't abstract until you have seen the pattern three times. Three similar lines beat a premature abstraction.
• Prefer specific, composable logic over abstract frameworks.
• Evolve the design incrementally rather than perfecting it upfront, and don't build for hypothetical future requirements.
• Document the trade-off when making a non-obvious choice.

Before implementing a feature, read references/property-driven-design.md. Property questions surface design gaps — deleted entities, case sensitivity, tie-breaking — during design rather than during debugging.

File organization

• Name files for what they contain, never a generic category: string-formatting.ts, date-arithmetic.ts, user-validation.ts, not utils.ts or helpers.ts. When tempted to create one of those, ask what the functions have in common and name the file after that.
• Keep module boundaries strict, with restricted visibility.
• Platform-specific code goes in its own file: unix.ts, windows.ts, posix.ts, selected by conditional compilation or a runtime check.
• Test helpers belong in dedicated modules, not mixed into production code.
• Prefer many small files to a few large ones.

Style

• Keep the happy path left-aligned. Return early instead of nesting.
• Declare identifiers in the files that need them; export or make public only when something else needs them.
• Declare variables close to their usage.
• Limit assignment scope — reassignment and shadowing cause subtle bugs.

Code comments

REQUIRED: Load the 'house-style-code-comments' skill for the comment policy.