[codex] Enforce Effect error handling conventions

[juliusmarminge]

Summary

• require Effect.catchTags for statically known tagged failures while preserving exhaustive and structural catch exceptions
• reject constructor-only error aliases that hide structured attributes and causes
• guide reusable error-to-error translations toward descriptive static factories on the target error class

Validation

• pnpm vp check
• pnpm vp run typecheck

---

Note

Low Risk
Documentation-only change to CI check-run agent guidelines; no runtime or production code paths are modified.

Overview
Updates the Effect Service Conventions Macroscope check-run agent (.macroscope/check-run-agents/effect-service-conventions.md) so automated reviews enforce stricter error-handling patterns—no application code changes.

The Errors and predicates section gains guidance on bounded, safe error/log fields (no raw secrets or wire payloads in message/detail), pass-through of structured domain errors at translation boundaries, mandatory Effect.catchTags for known tagged failures (instead of catchTag / predicate catchIf), rejection of trivial error constructor helpers, and preferring static factories on target error classes for reusable mappings.

The agent model is switched from claude-opus-4-8 to claude-opus-4-7.

^{Reviewed by Cursor Bugbot for commit 69ab586. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Enforce Effect error handling conventions in codex guidelines

Updates effect-service-conventions.md with additional rules in the Errors and predicates section:

• Keep error attributes and log annotations bounded; avoid including raw unsafe data
• Pass through already-structured domain errors at translation boundaries; only wrap unknown or lower-level failures
• Prefer Effect.catchTags over catchIf/catchTag for handling known tagged failures
• Prohibit trivial helper constructors that only instantiate an error class
• Prefer static factory methods on error classes for reusable error-to-error translations, but avoid forcing static methods for one-off cases

^{Macroscope summarized 69ab586.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ff98dd2e-c4b7-41a6-9a3f-59c7128fd527

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/effect-error-review-rules

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Changes to Macroscope configuration files (.macroscope/ directory) control how the review system analyzes code and should be verified by a human to ensure the intended behavior.

^{You can customize Macroscope's approvability policy. Learn more.}