Effect v4 review
Review program behavior and the contracts it exposes. Prefer Effect primitives
when they remove custom cancellation, scheduling, resource, or coordination
logic. Explain the semantic benefit; counting Effect APIs is not a measure of
code quality.
Use this skill read-only unless the user also requests fixes. When asked to
review or improve this skill itself, inspect its instructions and examples;
do not launch a product-code audit.
Default to one reviewer: the current agent, with zero subagents, including
whole-repository audits. Follow the delegation and context limits in section 3.
1. Establish scope and ground truth
Read version-grounding.md and the applicable
repository instructions before making findings.
- Respect explicit files/directories, PRs, branches, and prior conversation.
"My changes" normally means working changes when present; otherwise inspect
the current branch's actual base. State inferred scope. Ask only if unresolved
ambiguity would materially change the review.
- PR/branch: determine the actual base, inspect its merge-base diff and relevant
callers. Working changes: include staged, unstaged, and relevant untracked
files. An empty diff is not a command failure. Never silently review
HEAD~1.
- Repo: discover first-party source, excluding generated/dependency/reference
trees.
.context is API evidence, not product code under review.
- Classify by contents and ownership, not extension alone.
index.ts, config,
.tsx, .spec.*, and type tests can contain important Effect behavior.
Include indirect consumers and runtime adapters when following a contract.
- Pin actual package resolution and patches. Skill examples are evidence for
their tested version, not authority over a different installed version.
Optional read-only inventory helper (supply actual paths):
node <skill>/scripts/inspect-project.mjs --project <repo> --mode working
node <skill>/scripts/inspect-project.mjs --project <repo> --mode diff --base <actual-base>
node <skill>/scripts/inspect-project.mjs --project <repo> --mode repo
The helper lists candidates and exclusions; it does not claim semantic review
coverage or discover a PR base for you. Narrow to user-requested paths and read
relevant non-source contracts too.
2. Review connected behavior
Read known-pitfalls.md for conditions that made
previous proposed fixes unsafe. Then follow the relevant path:
input → schema → service → driver/resource → error mapping → consumer → test.
Run the error and lifetime passes on effectful work before suggesting style
changes. Load other references when their concerns are present:
| Concern |
Reference |
| Expected failures, defects, interruption, recovery, public contracts |
errors-and-cause.md |
| Resource scopes, fibers, cancellation, state, backpressure |
resources-concurrency.md |
| Primitive selection; HTTP, retry, caching, polling, data transforms |
primitives.md |
| Lazy construction, generators, tracing, Promise interop |
effect-fn-and-gen.md |
| Dependencies, layer acquisition/memoization, configuration |
services-layers.md |
| Decode/construction/encode, optionality, brands |
schema.md |
| Trace/log/metric context, status, export lifetime |
observability.md |
| Atom identity, runtime ownership, async state, invalidation |
effect-atom.md |
| Behavior assertions, clocks, layers, typed failures |
test-patterns.md |
For each custom mechanism, consider an existing Effect primitive or repository
abstraction. Check API availability, lifetime, failure/cancellation semantics,
performance, and affected callers before recommending it. Short combinator
chains, local variables, exhaustive switches, and native boundary adapters can
be the clearest correct implementation.
3. Review with one agent by default
Delegation budget: zero by default; at most two subagents in total when the
user explicitly requests parallel or independent agent review. Repository
size, file count, available slots, or a request for a thorough audit do not
authorize delegation. Do not ask to add agents routinely; continue locally.
An explicitly requested higher count can override this limit, subject to host
rules. A smaller user/host limit always applies.
- The cap is for the entire review, not concurrent agents or each wave. Count
every distinct delegated reviewer, including reused agents. Never reset the
budget for another concern, phase, retry, or verification pass.
- No recursive delegation. Every delegated reviewer must work alone. Do not
create one agent per file, concern, finding, or shard-and-concern pair.
- Delegate only bounded, independent work that avoids duplicating the main
review. Assign distinct subsystems, or a specific unresolved claim when an
independent check was requested. Keep integration and final verification
with the main reviewer; no automatic second team of verifiers.
- Send a compact task with assigned paths, resolved versions/patches, applicable
conventions, relevant reference paths, and the expected result. Avoid copying
the full conversation, entire skill/reference set, diffs, or repository into
each prompt. Select isolated/no-history context when supported: a short prompt
alone does not prevent the host from inheriting the full conversation.
Reviewers may read callers outside their assignment as evidence.
- Ask for confirmed findings, necessary evidence, and material coverage gaps,
normally within 600 words per delegated report. Use file references for long
reproductions; do not repeat source dumps or narrate every inspected file.
- When the budget is used up or a reviewer fails, finish the remaining work
locally. Reuse an existing reviewer only for a specific missing check; do not
restart completed reviews or add replacement agents to bypass the cap.
Review connected paths once and apply relevant concerns together. Cache the
resolved version/policy evidence in a short note; load only relevant reference
sections. Keep a compact coverage ledger for large audits and continue
sequentially without re-reading completed areas unless new evidence requires it.
Preserve requested coverage and consequential verification; report any actual
omissions. Do not assume particular tools, models, or token-meter availability,
and do not claim measured token savings without measurements.
4. Verify and report
Follow review-protocol.md. Every proposed API,
including optional suggestions, needs version-matched evidence. Consequential
findings need a concrete trigger and positive supporting evidence plus an
attempt to refute them.
Keep three kinds of output separate:
- Correctness: an observable failure, lost guarantee, or demonstrated cost.
- Repository policy: an applicable local requirement, cited to its source.
- Optional simplification: clearer primitive use with preserved behavior;
never a blocking defect merely because syntax differs.
Comments are evidence of intent, not immunity. An unsafe proposed fix does not
refute a real bug. Keep unresolved claims in open questions, not downgraded
findings. Preserve uncertainty when execution or source evidence is missing.
Report highest-impact confirmed findings first, with location, trigger, impact,
rule, evidence, fix direction/risk, and validation. Include scope, coverage and
checks performed. Keep optional improvements concise and separate. If no
confirmed defect was found, say so with material coverage limits. Omit empty
category sections, numeric compliance scores, and file rankings.
Maintaining this skill
Complete TypeScript examples live in examples/README.md
and adjacent source files; do not duplicate them into unchecked GOOD blocks.
They include negative-control tests proving why unsafe patterns fail. Run
scripts/check-examples.mjs --project <repo> with Node and the project's
installed dependencies; it does not install or upgrade packages.
When API/runtime guidance or dependencies change, verify affected source and
patches and run affected examples. For instruction-only changes, check metadata,
links, and consistency; do not automatically launch agents or a full benchmark.
Use evals/evals.json for a requested review-behavior comparison,
under the same total delegation budget. Ordinary code reviews do not run this
skill's maintenance evaluations.
See evals/README.md. Keep snapshots/results outside every
skill-discovery root, for example ~/.agents/skill-workspaces/effect-review-v4.
A backup containing SKILL.md under ~/.agents/skills can be discovered as
another installed skill even when it is outside this skill's own directory.
1---
2name: effect-review-v4
3description: >-
4 Review Effect v4 code, including beta, RC, and release versions, for correct
5 error propagation, resource ownership, cancellation, concurrency, primitive
6 selection, services/layers, schemas, atoms, observability, and tests. Use for
7 requests such as "effect v4 review", "review my Effect 4 changes", "check
8 Effect patterns", or "audit the Effect codebase" when the project uses v4.
9 Supports files, working changes, PR/branch diffs, and repository audits.
10 Reviews with one agent by default; delegation has an explicit total limit.
11 Verify APIs against the installed version. For Effect v3 use effect-review.
12metadata:
13 source: https://skillmd.com/skills/makisuo/effect-review-v4
14 version: "4.0.1"
15 examples-verified-with: "effect and @effect/vitest 4.0.0-rc.111"
16---
17
18# Effect v4 review
19
20Review program behavior and the contracts it exposes. Prefer Effect primitives
21when they remove custom cancellation, scheduling, resource, or coordination
22logic. Explain the semantic benefit; counting Effect APIs is not a measure of
23code quality.
24
25Use this skill read-only unless the user also requests fixes. When asked to
26review or improve this skill itself, inspect its instructions and examples;
27do not launch a product-code audit.
28
29Default to **one reviewer: the current agent, with zero subagents**, including
30whole-repository audits. Follow the delegation and context limits in section 3.
31
32## 1. Establish scope and ground truth
33
34Read [version-grounding.md](references/version-grounding.md) and the applicable
35repository instructions before making findings.
36
37- Respect explicit files/directories, PRs, branches, and prior conversation.
38 "My changes" normally means working changes when present; otherwise inspect
39 the current branch's actual base. State inferred scope. Ask only if unresolved
40 ambiguity would materially change the review.
41- PR/branch: determine the actual base, inspect its merge-base diff and relevant
42 callers. Working changes: include staged, unstaged, and relevant untracked
43 files. An empty diff is not a command failure. Never silently review `HEAD~1`.
44- Repo: discover first-party source, excluding generated/dependency/reference
45 trees. `.context` is API evidence, not product code under review.
46- Classify by contents and ownership, not extension alone. `index.ts`, config,
47 `.tsx`, `.spec.*`, and type tests can contain important Effect behavior.
48 Include indirect consumers and runtime adapters when following a contract.
49- Pin actual package resolution and patches. Skill examples are evidence for
50 their tested version, not authority over a different installed version.
51
52Optional read-only inventory helper (supply actual paths):
53
54```sh
55node <skill>/scripts/inspect-project.mjs --project <repo> --mode working
56node <skill>/scripts/inspect-project.mjs --project <repo> --mode diff --base <actual-base>
57node <skill>/scripts/inspect-project.mjs --project <repo> --mode repo
58```
59
60The helper lists candidates and exclusions; it does not claim semantic review
61coverage or discover a PR base for you. Narrow to user-requested paths and read
62relevant non-source contracts too.
63
64## 2. Review connected behavior
65
66Read [known-pitfalls.md](references/known-pitfalls.md) for conditions that made
67previous proposed fixes unsafe. Then follow the relevant path:
68
69**input → schema → service → driver/resource → error mapping → consumer → test**.
70
71Run the error and lifetime passes on effectful work before suggesting style
72changes. Load other references when their concerns are present:
73
74| Concern | Reference |
75| --- | --- |
76| Expected failures, defects, interruption, recovery, public contracts | [errors-and-cause.md](references/errors-and-cause.md) |
77| Resource scopes, fibers, cancellation, state, backpressure | [resources-concurrency.md](references/resources-concurrency.md) |
78| Primitive selection; HTTP, retry, caching, polling, data transforms | [primitives.md](references/primitives.md) |
79| Lazy construction, generators, tracing, Promise interop | [effect-fn-and-gen.md](references/effect-fn-and-gen.md) |
80| Dependencies, layer acquisition/memoization, configuration | [services-layers.md](references/services-layers.md) |
81| Decode/construction/encode, optionality, brands | [schema.md](references/schema.md) |
82| Trace/log/metric context, status, export lifetime | [observability.md](references/observability.md) |
83| Atom identity, runtime ownership, async state, invalidation | [effect-atom.md](references/effect-atom.md) |
84| Behavior assertions, clocks, layers, typed failures | [test-patterns.md](references/test-patterns.md) |
85
86For each custom mechanism, consider an existing Effect primitive or repository
87abstraction. Check API availability, lifetime, failure/cancellation semantics,
88performance, and affected callers before recommending it. Short combinator
89chains, local variables, exhaustive switches, and native boundary adapters can
90be the clearest correct implementation.
91
92## 3. Review with one agent by default
93
94**Delegation budget: zero by default; at most two subagents in total when the
95user explicitly requests parallel or independent agent review.** Repository
96size, file count, available slots, or a request for a thorough audit do not
97authorize delegation. Do not ask to add agents routinely; continue locally.
98An explicitly requested higher count can override this limit, subject to host
99rules. A smaller user/host limit always applies.
100
101- The cap is for the entire review, not concurrent agents or each wave. Count
102 every distinct delegated reviewer, including reused agents. Never reset the
103 budget for another concern, phase, retry, or verification pass.
104- No recursive delegation. Every delegated reviewer must work alone. Do not
105 create one agent per file, concern, finding, or shard-and-concern pair.
106- Delegate only bounded, independent work that avoids duplicating the main
107 review. Assign distinct subsystems, or a specific unresolved claim when an
108 independent check was requested. Keep integration and final verification
109 with the main reviewer; no automatic second team of verifiers.
110- Send a compact task with assigned paths, resolved versions/patches, applicable
111 conventions, relevant reference paths, and the expected result. Avoid copying
112 the full conversation, entire skill/reference set, diffs, or repository into
113 each prompt. Select isolated/no-history context when supported: a short prompt
114 alone does not prevent the host from inheriting the full conversation.
115 Reviewers may read callers outside their assignment as evidence.
116- Ask for confirmed findings, necessary evidence, and material coverage gaps,
117 normally within 600 words per delegated report. Use file references for long
118 reproductions; do not repeat source dumps or narrate every inspected file.
119- When the budget is used up or a reviewer fails, finish the remaining work
120 locally. Reuse an existing reviewer only for a specific missing check; do not
121 restart completed reviews or add replacement agents to bypass the cap.
122
123Review connected paths once and apply relevant concerns together. Cache the
124resolved version/policy evidence in a short note; load only relevant reference
125sections. Keep a compact coverage ledger for large audits and continue
126sequentially without re-reading completed areas unless new evidence requires it.
127Preserve requested coverage and consequential verification; report any actual
128omissions. Do not assume particular tools, models, or token-meter availability,
129and do not claim measured token savings without measurements.
130
131## 4. Verify and report
132
133Follow [review-protocol.md](references/review-protocol.md). Every proposed API,
134including optional suggestions, needs version-matched evidence. Consequential
135findings need a concrete trigger and positive supporting evidence plus an
136attempt to refute them.
137
138Keep three kinds of output separate:
139
140- **Correctness:** an observable failure, lost guarantee, or demonstrated cost.
141- **Repository policy:** an applicable local requirement, cited to its source.
142- **Optional simplification:** clearer primitive use with preserved behavior;
143 never a blocking defect merely because syntax differs.
144
145Comments are evidence of intent, not immunity. An unsafe proposed fix does not
146refute a real bug. Keep unresolved claims in open questions, not downgraded
147findings. Preserve uncertainty when execution or source evidence is missing.
148
149Report highest-impact confirmed findings first, with location, trigger, impact,
150rule, evidence, fix direction/risk, and validation. Include scope, coverage and
151checks performed. Keep optional improvements concise and separate. If no
152confirmed defect was found, say so with material coverage limits. Omit empty
153category sections, numeric compliance scores, and file rankings.
154
155## Maintaining this skill
156
157Complete TypeScript examples live in [examples/README.md](examples/README.md)
158and adjacent source files; do not duplicate them into unchecked GOOD blocks.
159They include negative-control tests proving why unsafe patterns fail. Run
160`scripts/check-examples.mjs --project <repo>` with Node and the project's
161installed dependencies; it does not install or upgrade packages.
162
163When API/runtime guidance or dependencies change, verify affected source and
164patches and run affected examples. For instruction-only changes, check metadata,
165links, and consistency; do not automatically launch agents or a full benchmark.
166Use [evals/evals.json](evals/evals.json) for a requested review-behavior comparison,
167under the same total delegation budget. Ordinary code reviews do not run this
168skill's maintenance evaluations.
169See [evals/README.md](evals/README.md). Keep snapshots/results outside every
170skill-discovery root, for example `~/.agents/skill-workspaces/effect-review-v4`.
171A backup containing `SKILL.md` under `~/.agents/skills` can be discovered as
172another installed skill even when it is outside this skill's own directory.