Prelude

Bootstrap a TypeScript Prelude

A prelude is an explicitly imported module for ambient helpers and types: ubiquitous, domain-neutral building blocks that have no more precise owner. Use the bundled prelude.ts as the foundation, then adapt it to evidence from the target repository. Apply ../coding-standards/SKILL.md throughout.

Ambient describes a helper's role, not a TypeScript global. Keep prelude exports behind ordinary imports; do not add global declarations or global augmentation.

1. Map the repository

Read repository instructions, package manifests, TypeScript configuration, source layout, and import conventions. Locate:

• an existing prelude or equivalent shared module;
• files named utils, helpers, common, types, result, errors, or similar;
• generic type aliases and tiny generic functions repeated across modules;
• established libraries for results, schemas, redaction, branding, collections, and exhaustive matching;
• every caller of plausible ambient helpers.

Search by both filenames and concepts. Use the ubiquitous generic helper/type categories in the coding standards as seed search terms, then inspect definitions and callers rather than classifying from names alone.

Completion criterion: Every plausible ambient definition found by repository-wide filename, symbol, and duplication scans is inventoried with its owner, callers, dependencies, and current behavior.

2. Classify every candidate

A symbol belongs in the prelude when all of these hold:

• it is domain-neutral and useful across unrelated modules;
• no domain, application service, adapter, protocol, or focused generic module is a more precise owner;
• centralizing it reduces duplication or gives a ubiquitous concept one canonical implementation;
• its dependencies are minimal, stable, and already justified by the project;
• its behavior is small enough to understand at the import site or hidden behind a precise type.

Keep a symbol with its focused owner when it encodes domain meaning, application policy, boundary translation, framework behavior, I/O, or a cohesive generic concept such as string casing or non-trivial collection operations. Prefer an established library over a local duplicate. A prelude is a curated foundation, not a barrel or miscellaneous dumping ground.

Record one decision for every candidate: use the established library, keep the current owner, move into the prelude, merge with a template symbol, or delete as an unused duplicate.

Completion criterion: Every inventoried candidate has one decision grounded in its semantics and callers; no candidate remains classified only by its filename or name.