adopt_skill

Overview

This skill helps migrate a TypeScript codebase from try/catch and Promise-based error handling to typed Result-based flows using better-result. It guides adoption at I/O boundaries, defines error categories, and shows concrete pattern transformations (sync, async, null checks, and generator composition). The focus is on creating TaggedError types and introducing railway-oriented programming without a full rewrite all at once.

How this skill works

The skill inspects code for throw sites, try/catch blocks, Promise.catch usage, and nullable patterns and recommends replacements using Result.try, Result.tryPromise, Result.ok/err and Result.gen. It prescribes a boundary-first migration: wrap external I/O with Result.try/tryPromise, convert internal checks to Result chains or Result.gen, and update signatures to return Result<T,E>. It also suggests TaggedError definitions and how to preserve error causes and contexts.

When to use it

• Adopting better-result in an existing TypeScript codebase
• Converting imperative try/catch blocks into typed Result returns
• Replacing thrown exceptions or Promise rejections with TaggedError types
• Migrating Promise-based async functions to Result.tryPromise
• Refactoring callback-heavy code to generator-based Result.gen composition

Best practices

• Start at boundaries (API, DB, file I/O) and migrate inward rather than rewriting everything
• Define clear TaggedError classes for domain and infrastructure errors; include cause and context
• Wrap only boundary or throwing functions with Result.try/tryPromise to avoid over-wrapping
• Convert nullable returns to Result.ok/err so callers get typed errors instead of null checks
• Use Result.gen for multi-step flows to produce a union error type and linear control flow
• Keep bugs/defects as thrown errors (Panic) and treat them differently from recoverable domain errors

Example use cases

• Replace JSON.parse try/catch with Result.try returning ParseError
• Wrap fetch calls with Result.tryPromise yielding ApiError or UnhandledException
• Convert functions that return null for missing entities into Result<User, NotFoundError>
• Refactor an async order processing flow into Result.gen to eliminate nested try/catch and propagate typed errors
• Audit a module for thrown exceptions and introduce TaggedError types at I/O boundaries