[juliusmarminge]

Problem

Reusable Effect functions have drifted back to wrappers around Effect.gen, making operation boundaries and tracing inconsistent. The repository guidance did not clearly preserve the earlier Effect.fn migration.

Change

Document named Effect.fn as the default for reusable operations, reserve Effect.fnUntraced for explained hot paths or existing spans, and retain Effect.gen for inline programs and layer construction. Keep the contributor guidance and review-agent conventions aligned.

Tracing choices

• Named Effect.fn("Service.operation") is the default for reusable service and I/O operations, giving each operation a stable span.
• Effect.fnUntraced is reserved for explained per-event or per-chunk work, tight loops, long-running pollers, or helpers that must retain an existing span. Inline programs and layer construction can still use Effect.gen. This layer documents the choices; it does not change runtime code.

Scope and approval

Maintainer-requested foundation of the Effect function migration stack, authored by juliusmarminge (maintainer list). This layer only clarifies the established Effect coding convention in contributor and review documentation. It introduces no feature, product default, or runtime behavior change, so the prior product-direction discussion requirement does not apply. No separate approval discussion is required for this documentation-only scope.

Verification

Reviewed AGENTS.md, docs/internals/effect-services.md, and .macroscope/check-run-agents/effect-service-conventions.md together for consistent tracing and execution-semantics guidance. All eight required checks passed on this head. No runtime tests or UI screenshots are applicable to this documentation-only layer.

Diff with whitespace ignored

View	Added lines	Removed lines
Normal diff	34	0
Whitespace ignored (git diff -w)	34	0

Review the files with whitespace hidden. These counts and the patch below are a snapshot of 8e658fb, compared with this PR's merge base. Whitespace-only changes are ignored; line wrapping and other textual changes still count.

Expand the full whitespace-ignored patch (3 files; unchanged context omitted)

diff --git a/.macroscope/check-run-agents/effect-service-conventions.md b/.macroscope/check-run-agents/effect-service-conventions.md
index 624018f781..f7cef3929a 100644
--- a/.macroscope/check-run-agents/effect-service-conventions.md
+++ b/.macroscope/check-run-agents/effect-service-conventions.md
@@ -46,0 +47,12 @@ Review changed TypeScript for the conventions below. They apply when a pull requ
+## Effect functions and tracing
+
+- Reusable functions use named `Effect.fn("Service.operation")`, not functions wrapping
+  `Effect.gen`. Inline programs, callbacks, and layer construction can keep `Effect.gen`.
+- Named `Effect.fn` creates a span; the unnamed form does not. Default to named spans for service
+  operations and I/O. `Effect.fnUntraced` is deliberate for per-chunk/per-event work, tight loops,
+  or helpers duplicating an existing tracing boundary; require a nearby reason for new uses.
+- Preserve existing span names/options and avoid adding duplicate spans. Pass combinators after
+  the generator body; transforms receive the original function arguments after the effect.
+- Preserve generic signatures, laziness, resource scope, and interruption behavior. An explicit
+  generator return type is `Effect.fn.Return<A, E, R>`.
+
diff --git a/AGENTS.md b/AGENTS.md
index 810d26e313..4dc489fafa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -155,0 +156,6 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
+- Reusable Effect functions use `Effect.fn("Service.operation")` with a stable span name, not a
+  function wrapping `Effect.gen`. Keep `Effect.gen` for inline programs and layer construction.
+  Use `Effect.fnUntraced` only when spans would be too frequent (stream chunks, per-event
+  projection, tight loops) or duplicate an existing tracing boundary; explain that choice nearby.
+  Named `Effect.fn` creates a span; the unnamed form does not. Preserve existing span names and
+  options, and pass combinators as additional function-builder arguments.
diff --git a/docs/internals/effect-services.md b/docs/internals/effect-services.md
index c29016dbf8..f2d93b9d8e 100644
--- a/docs/internals/effect-services.md
+++ b/docs/internals/effect-services.md
@@ -92,0 +93,16 @@ export const layer = Layer.effect(Foo, make);
+## Effect functions and tracing
+
+Reusable functions use `Effect.fn("Service.operation")`, not an arrow or declaration returning
+`Effect.gen`. The named form creates a span; `Effect.fn(function* ...)` only captures stack
+frames. Keep `Effect.gen` for inline programs, callbacks, and layer construction.
+
+Default to named spans for service operations and I/O. Use `Effect.fnUntraced` deliberately for
+per-chunk/per-event work, tight loops, or helpers already covered by the same operation's span.
+Explain the reason beside the function or a group of related functions. A loop is not by itself
+an exemption: its outer operation can still have a useful span without tracing each iteration.
+Preserve existing span names and options instead of adding a second span for the same operation.
+
+Pass effect combinators after the generator body. A transform that needs the function's input
+receives it after the effect. Use `Effect.fn.Return<A, E, R>` when the generator needs an explicit
+return type, and preserve generic parameters, laziness, scope, and interruption behavior.
+

Model: GPT-6.1 Sol. Harness: Codex.

[macroscopeapp]

Approvability

Verdict: Needs Human Approval

Macroscope's review found this PR requires human approval — The PR adds Effect tracing conventions to repository documentation and to a Macroscope check-run agent configuration. The documentation is non-runtime, but the .macroscope change alters automated review behavior and requires human review under the repository criteria.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 5c4649fa-4dd9-4b6f-8870-31c9d326f666

📥 Commits

Reviewing files that changed from the base of the PR and between 673c5e3 and 446028b.

📒 Files selected for processing: 3

• .macroscope/check-run-agents/effect-service-conventions.md
• AGENTS.md
• docs/internals/effect-services.md

Limit details: You’ve used all 10 included reviews currently available.

📝 Walkthrough

Added conventions for reusable Effect functions, tracing spans, untraced exceptions, combinator placement, and preservation of type and execution semantics across repository guidance and service documentation.

Changes: Effect service conventions

Layer / File(s)	Summary
Document Effect function conventions AGENTS.md, docs/internals/effect-services.md, .macroscope/check-run-agents/effect-service-conventions.md	The guidance describes named spans for reusable Effect functions, documented reasons for untraced functions, combinator placement, and preservation of generics and execution semantics.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Suggested reviewers: maria-rcks

Merge Risk: ⚪ Minimal · up to 44602

No merge-blocking risk was identified in these documentation-only changes.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main documentation change: establishing traced Effect function conventions.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description includes all required sections: Problem, Change, Scope and approval, and Verification. It explains the documentation-only scope, approval basis, affected guidance, verification perform…

Full details: Description check

Explanation

The description includes all required sections: Problem, Change, Scope and approval, and Verification. It explains the documentation-only scope, approval basis, affected guidance, verification performed, and why runtime tests and screenshots do not apply. It also includes the model and harness used.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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