[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M780HX7XVXNJWWBBVR3PFGME":3,"skill-same:01M780HX7XVXNJWWBBVR3PFGME":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M780HX7XVXNJWWBBVR3PFGME","effect-v4-planning",null,"Use when about to design, build, add, extend, or modify a feature, module, service, or schema in Effect v4 — before writing implementation code. Triggers on \"design\u002Fadd\u002Fbuild a feature\", \"new service\u002Fschema\u002Fmodule\", \"change\u002Frefactor existing Effect code\", and any moment you are reaching for Effect code without an explicit design first.","spencerbeggs\u002Feffected","spencerbeggs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F109114?v=4","01M77ZTHB70K5Y2VVTRCFY50A5","C. Spencer Beggs","01M77ZTHCC41NXBT3X906K6QM1",8,"MIT","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Feffect-v4-planning\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: effect-v4-planning\ndescription: Use when about to design, build, add, extend, or modify a feature, module, service, or schema in Effect v4 — before writing implementation code. Triggers on \"design\u002Fadd\u002Fbuild a feature\", \"new service\u002Fschema\u002Fmodule\", \"change\u002Frefactor existing Effect code\", and any moment you are reaching for Effect code without an explicit design first.\n---\n\n# Effect v4 feature planning\n\nThe orchestration skill. Every other `effect-v4-*` skill teaches *how to write*\none thing well; this one runs *before* them and decides *what to write*. It walks\nfour design pillars, then makes you emit a compact **design summary** and get\nbuy-in **before** any implementation code exists.\n\nWhy this skill exists: strong, skill-equipped agents — ones that already know the\napi-extractor-bases idiom, the layer-memoization discipline, `Clock` for testability — still\ndive straight to code, rationalize the decisions afterward, and **silently drop\nwhole pillars** (observability is the usual casualty). The mechanism that stops\nthat is not willpower; it is the required-slot summary below. You cannot leave the\nObservability row blank.\n\n## The recipe (do these in order — do not skip to code)\n\n1. **Locate the work on two axes, then check it can live where you're putting it.**\n   Answer all three before anything else:\n   - **Mode** — *greenfield* (new code) or *brownfield* (modifying existing code)?\n   - **Altitude** — *pure-tier* (parser \u002F engine \u002F schema library, no runtime\n     dependencies — semver\u002Fjsonc\u002Fyaml kind) or *service-tier* (real services,\n     layers, I\u002FO, lifecycle)?\n   - **Placement — does the target package's tier *admit* this capability?**\n     Confirm it before designing, not after. IO or a service dropped into a\n     pure-tier package (semver\u002Fjsonc\u002Fyaml\u002Fglob kind) is a **stop**, not a detail\n     to sort out later. And check the dependency direction against the peer\n     graph: a capability that must import a sibling which already peers on the\n     target closes a cycle. Adding `compileAndExpand` to pure-tier `glob` was\n     both — `walker` peers on `glob`, so it would have closed a `glob → walker →\n     glob` cycle, *and* it does filesystem IO in a pure package; it belonged in\n     `walker`. The repo's `CLAUDE.md` tier tags and the `effected-packages`\n     index are the authority on which package admits what — this was caught by\n     the tier tags, not by any skill, which is the gap this line closes.\n2. **Walk the four pillars** (below), routing into the detailed skill each owns.\n   Brownfield: read the existing code through each pillar as an *audit lens*.\n3. **Emit the design summary** — the required-slot block. Greenfield fills the\n   design template; brownfield fills the gap table.\n4. **Get buy-in, then build.** Present the summary and wait for the user before\n   writing implementation code. The summary is cheap to correct; code is not.\n   Two carve-outs, both below: a **delegated subagent** has no user to wait on, and a\n   **small pure-tier bugfix** collapses the summary to one line. Neither waives step 3.\n\n> Step 3 is not optional and not a formality. If you find yourself writing\n> `Schema.Struct`, `Context.Service`, or a `Layer` and no summary has been\n> emitted this turn, you skipped the recipe — stop and emit it.\n\n## The four pillars\n\nEach pillar: the decisions to make, the idiomatic ruling, and the skill that owns\nthe mechanics. Consult the linked skill; do not re-derive it here.\n\n### Pillar 0 — Pure core, effectful edge (runs before all four)\n\nNot a fifth pillar competing for a summary row — a cut you make **first**, that\nchanges what the other four are even about. Every feature that touches IO also\ncontains something that does not: a parse, a merge, a reconciliation, a decision\nabout what to write. Split them. Put the algorithm in a **pure surface** — a\n`Schema.Class` with statics, or a plain module of functions — and reduce the\nservice to a thin IO shell that reads, calls the pure thing, and writes.\n\n> Ask literally, before designing any service: **\"is any of this pure, and can it\n> be tested without a layer?\"** Whatever answers yes does not belong inside the\n> service.\n\nThe cautionary tale is one program old. A 90-line reconciliation algorithm was\nwritten *inside* a `Layer.effect` closure. Nothing about it needed the\nfilesystem — it took a desired state and an observed state and computed a diff —\nbut sealed in the layer, the only way to exercise it was to write real files,\nprovide a platform layer, run the effect, and read the files back. Every edge\ncase cost a fixture directory, so the edge cases did not get tested. Lifted out,\nit is a pure function with a table-driven unit test and no layer at all, and the\nservice shrinks to read → reconcile → write.\n\nTwo consequences the other pillars inherit:\n\n- **Pillar 2:** if the pure part is genuinely pure, the service is small enough\n  that \"no service at all\" is often the honest answer for it.\n- **Pillar 4:** a pure core is testable by construction. A test that needs a\n  temp directory to check an algorithm is a design smell, not a fixture problem.\n- Related but distinct — a pure helper left on a service *shape* also breaks\n  `Layer.mock`'s partiality (`effect-v4-services-layers`). Pure things belong on\n  pure surfaces for testing reasons and for wiring reasons; they are the same\n  reason.\n\nState the cut in the summary's Services\u002FLayers row: \"pure `X` + `Y` service as IO\nshell\", or \"no pure core — all of this is IO\" if you genuinely looked and found\nnone.\n\n### Pillar 1 — Data types & errors → `effect-v4-schema`, `effect-v4-idioms`, `hardening-a-parser-port`\n\n**Schemas.** Struct-vs-Class (Struct is the default; Class for behavior,\nequality, or a nominal domain type); optionality (`optionalKey` vs `optional` vs\n`NullOr` — pick deliberately per field); derive-over-rebuild (`Struct.pick\u002Fomit`,\nspread `.fields`) instead of parallel schemas; brand\u002F`Opaque` at boundaries where\ntwo same-shaped types must not mix (`UserId` vs `AccountId`); transformations as\nreusable codecs at the edges (`decodeTo`, with a fallible\n`SchemaGetter.transformEffect(...)` where the conversion can fail — there is no\ntop-level `Schema.transformEffect` in v4), domain model stays\nclean; validate late (shape first, business-rule `.check(...)` after).\n\n**Errors — name every fallible operation's error, and pin three attributes:**\n\n| Attribute | The decision |\n| ----------- | -------------- |\n| **Kind** | One aggregate error vs. several granular tagged errors? Recoverable typed error vs. a genuine defect? (Malformed *input* is always a typed error, never a defect — the `hardening-a-parser-port` invariant.) |\n| **Shape** | `Schema.TaggedError` with which structured fields? What does a caller need to *recover* — a `retryAfter`, a source position, a field path? |\n| **Audience** | Who consumes it? *End user* (a human-readable `message`), *calling code* (a stable `_tag` + structured fields to branch on), or *operator* (surfaced via a log\u002Fspan). Most errors serve two of these; state which. |\n\n**Input vs. wiring — the ruling.** Malformed *runtime input* is always a\nrecoverable typed error (the hardening invariant). A *developer wiring\u002Fconfig*\nerror — bad options passed to `static layer(opts)`, an invalid limit, a\nnonsensical duration — is a programming mistake: **strongly prefer a defect\nsurfaced at construction** (`Effect.die` \u002F a thrown validation) so the runtime\nerror channel stays exactly the domain errors a caller branches on. Override only\nfor a compelling reason — e.g. the config genuinely arrives from an untrusted or\nexternal source at runtime, or a caller must recover from a bad config — in which\ncase make it typed and say why in the summary.\n\nThe baseline failure this fixes: agents produce a good error by instinct but never\n*decide* its audience, so the shape drifts. Make it a decision, not an accident.\n\n### Pillar 2 — Services & Layers → `effect-v4-services-layers`\n\n**Contract inventory — the gate that runs before any service is modeled.**\nBefore designing any service, seam, or vocabulary, grep the vendored core\n(the tree's `packages\u002Feffect\u002Fsrc` — **including the `@stability unstable`\nnamespace modules**, which import exactly like any other core module and are\nnot partitioned into a separate directory; resolve the root via\n`effect-v4-source-lookup`)\nfor an existing contract. If core declares it, **require it in `R`** — do not\nre-declare it, re-implement it, or wrap it in a parallel vocabulary; the app\nprovides the platform layer at the edge. Evidence for why this is a hard gate:\nthe `@effected\u002Fcommands` package survived four review gates before a source\ncheck found `effect\u002Fprocess` already declared its entire surface —\nit was deleted the same day it was built. State the inventory result in the\ndesign summary (\"core declares X → required in R\" or \"no core contract found\nfor X\"). When a question survives the source read — semantics, not existence —\nsettle it with a probe per `effect-v4-source-lookup`; in a repo with a\n`scratchpad\u002F` workspace, write the probe there\n(`pnpm scratchpad:probe probes\u002F\u003Cname>.ts`).\n\n**Inventory core *and* the sibling `@effected` packages, not core alone.** In\nthis monorepo the likelier duplication is not a core primitive but a *sibling\nkit package that already owns the concept*. Before designing a local primitive,\nconsult the `effected-packages` index and grep the relevant sibling's `src`:\n`WorkspaceRoot.find`'s `stopAt` ceiling was about to be re-invented locally\nuntil a read of `Walker.ascend` found the concept already there with correct\ninclusive semantics. The core grep catches \"Effect already provides this\"; the\nsibling-package check catches \"another kit package already provides this\" — run\nboth, and state which authority you inventoried against.\n\nThe same grep doubles as a **style consult**: the vendored source is the\nparadigm reference, not just the API authority. Read how core writes the\nanalogous module — one concept per module, `Context.Service` contracts with a\n`make` that derives the surface from one primitive, branded scalars, `dual`\ncombinators, compiling doc examples — and match those paradigms in the design.\nDivergence is allowed but is a recorded decision with a reason, never a habit.\n\nWhat is the dependency closure? Model services with the v4 `Context.Service\u003CSelf,\nShape>()(\"id\")` form. **Design the Live\u002FTest layer split now** — it is pillar 4's\nraw material, not an afterthought. Composition posture (`mergeAll` vs `provide` vs\n`provideMerge`), provide-once-at-the-boundary, and build-once memoization (a\nparameterized `static layer(opts)` mints fresh state per call — bind it to a\n`const`). **Pure-tier default: no service at all** — a module of functions is\nusually right; do not manufacture a `Context.Service` for stateless pure code.\n\n### Pillar 3 — Observability → `effect-v4-observability` (and `effect-resource` for PubSub)\n\n**This is the pillar agents silently drop. It is a required row in the summary —\nfill it even if the answer is \"none.\"**\n\n- **Pure-tier:** defer to the house rule — named `Effect.fn` spans on public\n  fallible boundaries, *uniform* across a service's fallible methods, no metrics,\n  telemetry-agnostic. Often the whole answer is one line.\n- **Service-tier:** four rulings —\n  - **Inject a logger? No.** Do not parameterize a service with a logger.\n    Logging flows through the fiber via the `Effect.log*` family; `Logger` is\n    configured once at the app edge. A `logger` constructor parameter is the\n    anti-pattern.\n  - **Log format:** structured values (`Effect.logInfo(\"msg\", { key })`), never\n    concatenated strings, and only at boundaries.\n  - **OTel:** at the app edge only (core's `Otlp` layers from\n    `effect\u002Fobservability`, or the optional `@effect\u002Fopentelemetry` SDK bridge,\n    in one top-level layer). The service stays agnostic; libraries never import\n    an exporter.\n  - **PubSub \u002F events:** only when the feature is genuinely event-driven or\n    fan-out. Default is **no**. If yes, it is a `PubSub`\u002F`Queue` design decision —\n    see `effect-resource`.\n\n### Pillar 4 — Testability → `effect-v4-testing`\n\nDesign *for* the test now, so it is not retrofitted:\n\n- Dependencies are **injectable layers** (pillar 2's Test split) so collaborators\n  are mockable at the suite boundary via `layer(...)`.\n- Functions **return Effects** — never pre-run them; an `Effect.runSync`\u002F\n  `runPromise` in the API surface or a fixture is unmockable and untestable.\n- `it.effect` is the default runner; property-test over the pillar-1 schemas.\n- **Time \u002F schedules \u002F retries → `TestClock`.** If the feature reads the clock,\n  it must read it via `Clock`, and the test drives `TestClock.adjust`. A feature\n  that can only be tested against the wall clock is a design bug.\n\n## The design summary (REQUIRED — emit before coding)\n\n### Greenfield\n\n```text\n## Design: \u003Cfeature>\n- Altitude: pure-tier | service-tier\n- Data types: \u003Cschemas + Struct\u002FClass\u002Fbrand\u002Fcodec choices>\n- Errors: \u003CErrorName → kind \u002F shape \u002F audience>   (one row per error)\n- Services\u002FLayers: \u003Cservice(s) + Live\u002FTest split, OR \"none — plain module\">\n- Observability: \u003Cspans \u002F logging \u002F OTel \u002F PubSub posture — never blank>\n- Testing: \u003Crunner, mock layers, property targets, TestClock?>\n- Open risks: \u003Canything unresolved, or \"none\">\n```\n\n**A pure, total module may answer \"none\" on every service row — and that is a\nCOMPLETE design, not an evaded one.** For a module that is pure and total (no\nIO, no fallible operations, no services), a planning pass concluding \"no\nerror channel, no services, no observability\" is a legitimate complete answer\n(accepted as exactly that in review, 2026-08-14). The gate exists to force\nthe QUESTION, not to force machinery — manufacturing an error type or a\ndecorative span to avoid writing \"none\" is the same failure as leaving the\nrow blank.\n\n### Brownfield\n\nRead the existing code through each pillar, then emit a gap table. For each gap,\npre-fill a **recommended disposition** with a one-line reason so the user confirms\nor overrides in a single pass — do not silently refactor, and do not ask\ngap-by-gap:\n\n```text\n## Audit: \u003Cwhat you're changing>\n- Altitude: pure-tier | service-tier   Mode: brownfield\n\n| Pillar | Current | Best-practice target | Recommended disposition |\n|--------|---------|----------------------|-------------------------|\n| ...    | ...     | ...                  | refactor now \u002F incremental \u002F defer — \u003Cwhy> |\n```\n\nDispositions: **refactor now** (bring fully in line as part of this change),\n**improve incrementally** (fix only the surface you are already touching),\n**defer** (working code, out of scope — note it, move on). Options 2 and 3 keep\nthe change focused; do not scope-creep a refactor the user did not ask for.\n\n## Self-check before you present\n\n- Every fallible operation has a named typed error with a stated audience.\n- Pillar 0 was run: the pure part is named and lives outside the service, or you\n  can say why there isn't one. No algorithm is sealed in a `Layer.effect` closure.\n- No service takes a `logger` parameter.\n- Observability row matches altitude and is not blank.\n- Every service dependency has a Test layer, and time is read via `Clock`.\n- No `Effect.runSync`\u002F`runPromise` in the API surface or in a fixture.\n- Brownfield: every gap has a recommended disposition.\n\n## Two carve-outs from step 4 (buy-in)\n\nThe summary in step 3 is **never** waived. What bends is step 4 — *who* you wait for,\nand how heavy the summary has to be.\n\n### You are a delegated subagent — emit the summary, then proceed\n\nIf you are running as a headless subagent, **you have no user to wait on.** A\ndelegating parent dispatched you with instructions and is not watching the channel;\n\"present the summary and wait for buy-in\" would deadlock, and the usual failure is an\nagent that resolves the deadlock by quietly skipping step 3 altogether — losing the\naudit *and* the buy-in.\n\nSo: **emit the design summary, treat the parent's instructions as the buy-in, and\nproceed.** The summary is not wasted — it goes in your report, where it is exactly\nwhat lets the parent (and the reviewer on the PR) check the pillars were walked. What\nyou still owe splits by the *kind* of surprise the summary turns up:\n\n- A decision that **contradicts** the instructions — a scope change, a design you were\n  steered away from, a risk you cannot resolve — is a **stop**: do not proceed on your\n  own authority; report back and ask.\n- A decision that **exceeds** the instructions **without contradicting** them — the\n  instructed thing, done correctly, carries a consequence nobody named — is **proceed\n  AND flag**, not stop. Making an instructed `workspaceRoot` field *required* is the\n  correct design and *also* breaks decode for previously serialized values: you were\n  told to add the field, not to avoid the break, so proceeding is right — but the break\n  MUST land prominently in your report, never silently. Do the correct thing and surface\n  what it cost.\n\n- Evidence of a **concurrent writer in your assigned files** is a **stop**, and it is\n  neither of the two above — a *state* problem, not a design one. The signatures: an\n  edit you did not make appears between your read and your write; a declaration you\n  did not author (caught as `noRedeclare`); an Edit answered \"file changed since read\"\n  with your intended change *already applied*. That last one reads like a harness\n  quirk and is not — it is the collision signature. Stop writing immediately and\n  report to your coordinator, because the reconcile cost grows with every further\n  edit, and `git status` will NOT show you the other writer (uncommitted trees look\n  identical whoever wrote them). Two agents hit this unrouted in one session,\n  2026-07-28; the one that stopped early reconciled cleanly, the one that kept\n  writing spent the difference by hand.\n\nPut any genuinely unresolved item in the Open risks row rather than deciding it silently.\n\nAn interactive session has a real user: wait for them, as step 4 says.\n\n### Small pure-tier bugfix — a one-line summary is the whole recipe\n\nA bounded fix to an **existing pure-tier engine** (a perf fix, an off-by-one, a bad\nspan offset) does not need the brownfield gap table. It has no service, no layer, no\nobservability posture, and its testability is already settled by the existing suite;\nthe table's rows would all read \"n\u002Fa — unchanged\".\n\nQualifying is narrow. **All four** must hold: pure-tier; the fix is behaviour-\npreserving except for the bug itself; **no public API change**; and no new error case.\nMiss any one and you run the full brownfield audit — a bugfix that changes a signature\nor adds an error *is* a design change wearing a bugfix's clothes.\n\nWhen it qualifies, the summary collapses to one line, and you still emit it:\n\n```text\n## Fix: \u003Cbug> — pure-tier, no API change, no new error. Test: \u003Cthe test that now fails>.\n```\n\nThat last clause is the load-bearing one. The test that reproduces the bug *is* the\ndesign review for a fix this size: if you cannot name it, you do not understand the\nbug yet, and the fast path is not available to you.\n\n## Red flags — you skipped the recipe\n\n- You wrote `Schema.Struct` \u002F `Context.Service` \u002F `Layer.*` and no summary exists\n  this turn.\n- The Observability row is blank, or you never considered spans\u002Flogging.\n- You added a `logger` constructor parameter \"so it's testable.\"\n- You \"explained the design decisions\" *after* showing the code instead of\n  *before*.\n- Brownfield: you started editing existing code before auditing it against the\n  pillars.\n\n**Any of these: stop, run the recipe, emit the summary, get buy-in.**\n","# Effect v4 feature planning\n\nThe orchestration skill. Every other `effect-v4-*` skill teaches *how to write*\none thing well; this one runs *before* them and decides *what to write*. It walks\nfour design pillars, then makes you emit a compact **design summary** and get\nbuy-in **before** any implementation code exists.\n\nWhy this skill exists: strong, skill-equipped agents — ones that already know the\napi-extractor-bases idiom, the layer-memoization discipline, `Clock` for testability — still\ndive straight to code, rationalize the decisions afterward, and **silently drop\nwhole pillars** (observability is the usual casualty). The mechanism that stops\nthat is not willpower; it is the required-slot summary below. You cannot leave the\nObservability row blank.\n\n## The recipe (do these in order — do not skip to code)\n\n1. **Locate the work on two axes, then check it can live where you're putting it.**\n   Answer all three before anything else:\n   - **Mode** — *greenfield* (new code) or *brownfield* (modifying existing code)?\n   - **Altitude** — *pure-tier* (parser \u002F engine \u002F schema library, no runtime\n     dependencies — semver\u002Fjsonc\u002Fyaml kind) or *service-tier* (real services,\n     layers, I\u002FO, lifecycle)?\n   - **Placement — does the target package's tier *admit* this capability?**\n     Confirm it before designing, not after. IO or a service dropped into a\n     pure-tier package (semver\u002Fjsonc\u002Fyaml\u002Fglob kind) is a **stop**, not a detail\n     to sort out later. And check the dependency direction against the peer\n     graph: a capability that must import a sibling which already peers on the\n     target closes a cycle. Adding `compileAndExpand` to pure-tier `glob` was\n     both — `walker` peers on `glob`, so it would have closed a `glob → walker →\n     glob` cycle, *and* it does filesystem IO in a pure package; it belonged in\n     `walker`. The repo's `CLAUDE.md` tier tags and the `effected-packages`\n     index are the authority on which package admits what — this was caught by\n     the tier tags, not by any skill, which is the gap this line closes.\n2. **Walk the four pillars** (below), routing into the detailed skill each owns.\n   Brownfield: read the existing code through each pillar as an *audit lens*.\n3. **Emit the design summary** — the required-slot block. Greenfield fills the\n   design template; brownfield fills the gap table.\n4. **Get buy-in, then build.** Present the summary and wait for the user before\n   writing implementation code. The summary is cheap to correct; code is not.\n   Two carve-outs, both below: a **delegated subagent** has no user to wait on, and a\n   **small pure-tier bugfix** collapses the summary to one line. Neither waives step 3.\n\n> Step 3 is not optional and not a formality. If you find yourself writing\n> `Schema.Struct`, `Context.Service`, or a `Layer` and no summary has been\n> emitted this turn, you skipped the recipe — stop and emit it.\n\n## The four pillars\n\nEach pillar: the decisions to make, the idiomatic ruling, and the skill that owns\nthe mechanics. Consult the linked skill; do not re-derive it here.\n\n### Pillar 0 — Pure core, effectful edge (runs before all four)\n\nNot a fifth pillar competing for a summary row — a cut you make **first**, that\nchanges what the other four are even about. Every feature that touches IO also\ncontains something that does not: a parse, a merge, a reconciliation, a decision\nabout what to write. Split them. Put the algorithm in a **pure surface** — a\n`Schema.Class` with statics, or a plain module of functions — and reduce the\nservice to a thin IO shell that reads, calls the pure thing, and writes.\n\n> Ask literally, before designing any service: **\"is any of this pure, and can it\n> be tested without a layer?\"** Whatever answers yes does not belong inside the\n> service.\n\nThe cautionary tale is one program old. A 90-line reconciliation algorithm was\nwritten *inside* a `Layer.effect` closure. Nothing about it needed the\nfilesystem — it took a desired state and an observed state and computed a diff —\nbut sealed in the layer, the only way to exercise it was to write real files,\nprovide a platform layer, run the effect, and read the files back. Every edge\ncase cost a fixture directory, so the edge cases did not get tested. Lifted out,\nit is a pure function with a table-driven unit test and no layer at all, and the\nservice shrinks to read → reconcile → write.\n\nTwo consequences the other pillars inherit:\n\n- **Pillar 2:** if the pure part is genuinely pure, the service is small enough\n  that \"no service at all\" is often the honest answer for it.\n- **Pillar 4:** a pure core is testable by construction. A test that needs a\n  temp directory to check an algorithm is a design smell, not a fixture problem.\n- Related but distinct — a pure helper left on a service *shape* also breaks\n  `Layer.mock`'s partiality (`effect-v4-services-layers`). Pure things belong on\n  pure surfaces for testing reasons and for wiring reasons; they are the same\n  reason.\n\nState the cut in the summary's Services\u002FLayers row: \"pure `X` + `Y` service as IO\nshell\", or \"no pure core — all of this is IO\" if you genuinely looked and found\nnone.\n\n### Pillar 1 — Data types & errors → `effect-v4-schema`, `effect-v4-idioms`, `hardening-a-parser-port`\n\n**Schemas.** Struct-vs-Class (Struct is the default; Class for behavior,\nequality, or a nominal domain type); optionality (`optionalKey` vs `optional` vs\n`NullOr` — pick deliberately per field); derive-over-rebuild (`Struct.pick\u002Fomit`,\nspread `.fields`) instead of parallel schemas; brand\u002F`Opaque` at boundaries where\ntwo same-shaped types must not mix (`UserId` vs `AccountId`); transformations as\nreusable codecs at the edges (`decodeTo`, with a fallible\n`SchemaGetter.transformEffect(...)` where the conversion can fail — there is no\ntop-level `Schema.transformEffect` in v4), domain model stays\nclean; validate late (shape first, business-rule `.check(...)` after).\n\n**Errors — name every fallible operation's error, and pin three attributes:**\n\n| Attribute | The decision |\n| ----------- | -------------- |\n| **Kind** | One aggregate error vs. several granular tagged errors? Recoverable typed error vs. a genuine defect? (Malformed *input* is always a typed error, never a defect — the `hardening-a-parser-port` invariant.) |\n| **Shape** | `Schema.TaggedError` with which structured fields? What does a caller need to *recover* — a `retryAfter`, a source position, a field path? |\n| **Audience** | Who consumes it? *End user* (a human-readable `message`), *calling code* (a stable `_tag` + structured fields to branch on), or *operator* (surfaced via a log\u002Fspan). Most errors serve two of these; state which. |\n\n**Input vs. wiring — the ruling.** Malformed *runtime input* is always a\nrecoverable typed error (the hardening invariant). A *developer wiring\u002Fconfig*\nerror — bad options passed to `static layer(opts)`, an invalid limit, a\nnonsensical duration — is a programming mistake: **strongly prefer a defect\nsurfaced at construction** (`Effect.die` \u002F a thrown validation) so the runtime\nerror channel stays exactly the domain errors a caller branches on. Override only\nfor a compelling reason — e.g. the config genuinely arrives from an untrusted or\nexternal source at runtime, or a caller must recover from a bad config — in which\ncase make it typed and say why in the summary.\n\nThe baseline failure this fixes: agents produce a good error by instinct but never\n*decide* its audience, so the shape drifts. Make it a decision, not an accident.\n\n### Pillar 2 — Services & Layers → `effect-v4-services-layers`\n\n**Contract inventory — the gate that runs before any service is modeled.**\nBefore designing any service, seam, or vocabulary, grep the vendored core\n(the tree's `packages\u002Feffect\u002Fsrc` — **including the `@stability unstable`\nnamespace modules**, which import exactly like any other core module and are\nnot partitioned into a separate directory; resolve the root via\n`effect-v4-source-lookup`)\nfor an existing contract. If core declares it, **require it in `R`** — do not\nre-declare it, re-implement it, or wrap it in a parallel vocabulary; the app\nprovides the platform layer at the edge. Evidence for why this is a hard gate:\nthe `@effected\u002Fcommands` package survived four review gates before a source\ncheck found `effect\u002Fprocess` already declared its entire surface —\nit was deleted the same day it was built. State the inventory result in the\ndesign summary (\"core declares X → required in R\" or \"no core contract found\nfor X\"). When a question survives the source read — semantics, not existence —\nsettle it with a probe per `effect-v4-source-lookup`; in a repo with a\n`scratchpad\u002F` workspace, write the probe there\n(`pnpm scratchpad:probe probes\u002F\u003Cname>.ts`).\n\n**Inventory core *and* the sibling `@effected` packages, not core alone.** In\nthis monorepo the likelier duplication is not a core primitive but a *sibling\nkit package that already owns the concept*. Before designing a local primitive,\nconsult the `effected-packages` index and grep the relevant sibling's `src`:\n`WorkspaceRoot.find`'s `stopAt` ceiling was about to be re-invented locally\nuntil a read of `Walker.ascend` found the concept already there with correct\ninclusive semantics. The core grep catches \"Effect already provides this\"; the\nsibling-package check catches \"another kit package already provides this\" — run\nboth, and state which authority you inventoried against.\n\nThe same grep doubles as a **style consult**: the vendored source is the\nparadigm reference, not just the API authority. Read how core writes the\nanalogous module — one concept per module, `Context.Service` contracts with a\n`make` that derives the surface from one primitive, branded scalars, `dual`\ncombinators, compiling doc examples — and match those paradigms in the design.\nDivergence is allowed but is a recorded decision with a reason, never a habit.\n\nWhat is the dependency closure? Model services with the v4 `Context.Service\u003CSelf,\nShape>()(\"id\")` form. **Design the Live\u002FTest layer split now** — it is pillar 4's\nraw material, not an afterthought. Composition posture (`mergeAll` vs `provide` vs\n`provideMerge`), provide-once-at-the-boundary, and build-once memoization (a\nparameterized `static layer(opts)` mints fresh state per call — bind it to a\n`const`). **Pure-tier default: no service at all** — a module of functions is\nusually right; do not manufacture a `Context.Service` for stateless pure code.\n\n### Pillar 3 — Observability → `effect-v4-observability` (and `effect-resource` for PubSub)\n\n**This is the pillar agents silently drop. It is a required row in the summary —\nfill it even if the answer is \"none.\"**\n\n- **Pure-tier:** defer to the house rule — named `Effect.fn` spans on public\n  fallible boundaries, *uniform* across a service's fallible methods, no metrics,\n  telemetry-agnostic. Often the whole answer is one line.\n- **Service-tier:** four rulings —\n  - **Inject a logger? No.** Do not parameterize a service with a logger.\n    Logging flows through the fiber via the `Effect.log*` family; `Logger` is\n    configured once at the app edge. A `logger` constructor parameter is the\n    anti-pattern.\n  - **Log format:** structured values (`Effect.logInfo(\"msg\", { key })`), never\n    concatenated strings, and only at boundaries.\n  - **OTel:** at the app edge only (core's `Otlp` layers from\n    `effect\u002Fobservability`, or the optional `@effect\u002Fopentelemetry` SDK bridge,\n    in one top-level layer). The service stays agnostic; libraries never import\n    an exporter.\n  - **PubSub \u002F events:** only when the feature is genuinely event-driven or\n    fan-out. Default is **no**. If yes, it is a `PubSub`\u002F`Queue` design decision —\n    see `effect-resource`.\n\n### Pillar 4 — Testability → `effect-v4-testing`\n\nDesign *for* the test now, so it is not retrofitted:\n\n- Dependencies are **injectable layers** (pillar 2's Test split) so collaborators\n  are mockable at the suite boundary via `layer(...)`.\n- Functions **return Effects** — never pre-run them; an `Effect.runSync`\u002F\n  `runPromise` in the API surface or a fixture is unmockable and untestable.\n- `it.effect` is the default runner; property-test over the pillar-1 schemas.\n- **Time \u002F schedules \u002F retries → `TestClock`.** If the feature reads the clock,\n  it must read it via `Clock`, and the test drives `TestClock.adjust`. A feature\n  that can only be tested against the wall clock is a design bug.\n\n## The design summary (REQUIRED — emit before coding)\n\n### Greenfield\n\n```text\n## Design: \u003Cfeature>\n- Altitude: pure-tier | service-tier\n- Data types: \u003Cschemas + Struct\u002FClass\u002Fbrand\u002Fcodec choices>\n- Errors: \u003CErrorName → kind \u002F shape \u002F audience>   (one row per error)\n- Services\u002FLayers: \u003Cservice(s) + Live\u002FTest split, OR \"none — plain module\">\n- Observability: \u003Cspans \u002F logging \u002F OTel \u002F PubSub posture — never blank>\n- Testing: \u003Crunner, mock layers, property targets, TestClock?>\n- Open risks: \u003Canything unresolved, or \"none\">\n```\n\n**A pure, total module may answer \"none\" on every service row — and that is a\nCOMPLETE design, not an evaded one.** For a module that is pure and total (no\nIO, no fallible operations, no services), a planning pass concluding \"no\nerror channel, no services, no observability\" is a legitimate complete answer\n(accepted as exactly that in review, 2026-08-14). The gate exists to force\nthe QUESTION, not to force machinery — manufacturing an error type or a\ndecorative span to avoid writing \"none\" is the same failure as leaving the\nrow blank.\n\n### Brownfield\n\nRead the existing code through each pillar, then emit a gap table. For each gap,\npre-fill a **recommended disposition** with a one-line reason so the user confirms\nor overrides in a single pass — do not silently refactor, and do not ask\ngap-by-gap:\n\n```text\n## Audit: \u003Cwhat you're changing>\n- Altitude: pure-tier | service-tier   Mode: brownfield\n\n| Pillar | Current | Best-practice target | Recommended disposition |\n|--------|---------|----------------------|-------------------------|\n| ...    | ...     | ...                  | refactor now \u002F incremental \u002F defer — \u003Cwhy> |\n```\n\nDispositions: **refactor now** (bring fully in line as part of this change),\n**improve incrementally** (fix only the surface you are already touching),\n**defer** (working code, out of scope — note it, move on). Options 2 and 3 keep\nthe change focused; do not scope-creep a refactor the user did not ask for.\n\n## Self-check before you present\n\n- Every fallible operation has a named typed error with a stated audience.\n- Pillar 0 was run: the pure part is named and lives outside the service, or you\n  can say why there isn't one. No algorithm is sealed in a `Layer.effect` closure.\n- No service takes a `logger` parameter.\n- Observability row matches altitude and is not blank.\n- Every service dependency has a Test layer, and time is read via `Clock`.\n- No `Effect.runSync`\u002F`runPromise` in the API surface or in a fixture.\n- Brownfield: every gap has a recommended disposition.\n\n## Two carve-outs from step 4 (buy-in)\n\nThe summary in step 3 is **never** waived. What bends is step 4 — *who* you wait for,\nand how heavy the summary has to be.\n\n### You are a delegated subagent — emit the summary, then proceed\n\nIf you are running as a headless subagent, **you have no user to wait on.** A\ndelegating parent dispatched you with instructions and is not watching the channel;\n\"present the summary and wait for buy-in\" would deadlock, and the usual failure is an\nagent that resolves the deadlock by quietly skipping step 3 altogether — losing the\naudit *and* the buy-in.\n\nSo: **emit the design summary, treat the parent's instructions as the buy-in, and\nproceed.** The summary is not wasted — it goes in your report, where it is exactly\nwhat lets the parent (and the reviewer on the PR) check the pillars were walked. What\nyou still owe splits by the *kind* of surprise the summary turns up:\n\n- A decision that **contradicts** the instructions — a scope change, a design you were\n  steered away from, a risk you cannot resolve — is a **stop**: do not proceed on your\n  own authority; report back and ask.\n- A decision that **exceeds** the instructions **without contradicting** them — the\n  instructed thing, done correctly, carries a consequence nobody named — is **proceed\n  AND flag**, not stop. Making an instructed `workspaceRoot` field *required* is the\n  correct design and *also* breaks decode for previously serialized values: you were\n  told to add the field, not to avoid the break, so proceeding is right — but the break\n  MUST land prominently in your report, never silently. Do the correct thing and surface\n  what it cost.\n\n- Evidence of a **concurrent writer in your assigned files** is a **stop**, and it is\n  neither of the two above — a *state* problem, not a design one. The signatures: an\n  edit you did not make appears between your read and your write; a declaration you\n  did not author (caught as `noRedeclare`); an Edit answered \"file changed since read\"\n  with your intended change *already applied*. That last one reads like a harness\n  quirk and is not — it is the collision signature. Stop writing immediately and\n  report to your coordinator, because the reconcile cost grows with every further\n  edit, and `git status` will NOT show you the other writer (uncommitted trees look\n  identical whoever wrote them). Two agents hit this unrouted in one session,\n  2026-07-28; the one that stopped early reconciled cleanly, the one that kept\n  writing spent the difference by hand.\n\nPut any genuinely unresolved item in the Open risks row rather than deciding it silently.\n\nAn interactive session has a real user: wait for them, as step 4 says.\n\n### Small pure-tier bugfix — a one-line summary is the whole recipe\n\nA bounded fix to an **existing pure-tier engine** (a perf fix, an off-by-one, a bad\nspan offset) does not need the brownfield gap table. It has no service, no layer, no\nobservability posture, and its testability is already settled by the existing suite;\nthe table's rows would all read \"n\u002Fa — unchanged\".\n\nQualifying is narrow. **All four** must hold: pure-tier; the fix is behaviour-\npreserving except for the bug itself; **no public API change**; and no new error case.\nMiss any one and you run the full brownfield audit — a bugfix that changes a signature\nor adds an error *is* a design change wearing a bugfix's clothes.\n\nWhen it qualifies, the summary collapses to one line, and you still emit it:\n\n```text\n## Fix: \u003Cbug> — pure-tier, no API change, no new error. Test: \u003Cthe test that now fails>.\n```\n\nThat last clause is the load-bearing one. The test that reproduces the bug *is* the\ndesign review for a fix this size: if you cannot name it, you do not understand the\nbug yet, and the fast path is not available to you.\n\n## Red flags — you skipped the recipe\n\n- You wrote `Schema.Struct` \u002F `Context.Service` \u002F `Layer.*` and no summary exists\n  this turn.\n- The Observability row is blank, or you never considered spans\u002Flogging.\n- You added a `logger` constructor parameter \"so it's testable.\"\n- You \"explained the design decisions\" *after* showing the code instead of\n  *before*.\n- Brownfield: you started editing existing code before auditing it against the\n  pillars.\n\n**Any of these: stop, run the recipe, emit the summary, get buy-in.**\n",{"name":5,"description":7},"main","11d6b3ae59538b0e16ad67c315ecb0c25fcb0125","plugin\u002Fskills\u002Feffect-v4-planning",2,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected","https:\u002F\u002Fgithub.com\u002Fspencerbeggs","2026-11-14 07:03:25",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add spencerbeggs\u002Feffected --skill effect-v4-planning",{"tool":37,"command":38},"bunx","bunx skills add spencerbeggs\u002Feffected --skill effect-v4-planning",{"tool":40,"command":41},"pnpm","pnpm dlx skills add spencerbeggs\u002Feffected --skill effect-v4-planning","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Feffect-v4-planning\u002FSKILL.md",true,[],[46,53,60,67,74,81],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M780NVTD800KMFV869YNZED6","testing-actions","Use when writing or reviewing tests for @effected\u002Fgithub-actions, @effected\u002Fgithub, @effected\u002Fsbom or @effected\u002Fcommands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre\u002Fmain\u002Fpost lifecycle through Action.run, or debugging why a test hits the real network or hangs.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Ftesting-actions\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M780NPDSGFC0FCP7696NW11J","supply-chain-attestation","Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fsupply-chain-attestation\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M780NGP4QNZDH8T8Q8WZ18SA","structuring-an-action","Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fstructuring-an-action\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M780NCD52H1Y03FS83WJ8BT5","running-commands-and-tools","Use when running a subprocess in Effect v4, spawning a command, capturing stdout\u002Fstderr\u002Fexit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frunning-commands-and-tools\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M780N823DWNRMSY5X2NT5MSR","release-and-publish","Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frelease-and-publish\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M780MXRF6H20KCESTSSFB3HQ","hardening-a-parser-port","Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fhardening-a-parser-port\u002FSKILL.md",[],[]]