cratis-engineering-effect-boundaries

Enforce fail-loudly error handling on publish, persist, generate, and release boundaries.

3|Updated Dec 25, 2024
One-click install
npx skills add https://github.com/Cratis/Samples --skill cratis-engineering-effect-boundaries-cratis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cratis-engineering-effect-boundaries
Source: https://github.com/Cratis/Samples/tree/main/.cratis/ai/skills/cratis-engineering-effect-boundaries
Command: npx skills add https://github.com/Cratis/Samples --skill cratis-engineering-effect-boundaries-cratis

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Silent failure on effect boundaries — operations that publish, persist, generate, propagate, or release — is the dominant recurring bug archetype in Cratis codebases. Code catches exceptions and continues, maps unknown outcomes onto success, or reports a fan-out as done when only part of it succeeded, and the failure is discovered downstream by someone who cannot see the boundary that caused it. ## Core Features & Use Cases - Boundary identification: Name what leaves the process (packages, rows, files, repositories) before writing any error handler, and enumerate every outcome the call can produce, including unmodelled ones. - Three permitted degraded responses: Fail the operation, complete and surface the delta in the result, or emit an explicit degraded-mode signal — anything else is catch-and-continue. - Fan-out accounting: Report attempted, succeeded, and failed counts in results and summaries so "29 of 36" never reads as success. - Sibling implementation parity: Ensure in-memory and SQL implementations of an interface enforce the same constraints as the real store, or throw rather than silently accept. - Use Case: When reviewing a release action that catches an HTTP 422 from a registry, apply the contract to classify the conflict explicitly instead of reporting a successful release that never happened. ## Quick Start Review this error-handling code around the publish step using the effect-boundary contract and tell me whether any degraded outcome could still report success.

Frequently Asked Questions about cratis-engineering-effect-boundaries

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I handle errors on operations that publish or persist data?▼

Treat the operation as an effect boundary where partial success is failure. Enumerate every outcome the call can produce, then either fail the operation, surface the delta in the result, or emit an explicit degraded-mode signal the caller must handle.

What is an effect boundary in error handling?▼

An effect boundary is the point where work leaves the process and becomes observable by others: a package published, a row written, a file generated, content propagated, or a release cut. On those boundaries, catch-and-continue and defaulting to success on unknown outcomes are defects.

When does catch-and-continue not apply to this contract?▼

Pure computation with no effect, retries that still report the final outcome truthfully, and optional enrichments whose absence is stated in the result are exempt. Style questions and decisions about whether an operation should exist are also out of scope.

How should a fan-out or batch operation report partial failures?▼

Count attempted, succeeded, and failed separately and put all three numbers in the returned result and the summary line. A run that succeeded 29 of 36 times must read differently from a fully successful run, and unclassifiable outcomes are reported as indeterminate, never rolled into success.

Why do in-memory test implementations make specifications pass vacuously?▼

When an in-memory or SQL sibling of a real store does not enforce the same constraints, every specification written against it passes while proving nothing. Sibling implementations must match the primary one's semantics or throw rather than silently accept.

How do I verify a failure path actually works?▼

Plant the failure and watch it surface: inject the status code, delete an input, or fail one fan-out member, then confirm the operation fails, the delta appears, or the degraded signal fires. A boundary whose failure path was never executed is not known to have one.