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