failure-conditions
Conditions that fail a /create-module or /add-operation task on contact. Use when scoping work, reviewing a PR, or refusing a request that violates a hard rule.
SKILL.md.claude/skills/failure-conditions/SKILL.md
GitHubImmediate failure conditions
A task fails on the spot if any of these are true. The fix is always the same: don't do the thing.
Spec / codegen
describe*operationId — collides with mocha's BDD global. Rename toget*/list*/etc.- 4xx / 5xx response declared in
api.yml— the framework owns error mapping. Declare only 200/201. nullable: trueanywhere in the spec — codegen rejects it. UseoneOf: […, { type: 'null' }]or rethink the type.Inline*Response*/Inline*RequestBody*types ingenerated/—api.ymlhas an inline schema in a request/response body. Hoist it tocomponents/schemas/and$refit.- Schema used as a direct endpoint response and as a nested property of another schema, and it has 10+ properties — generated types will balloon. Create a
<Name>Summaryfor the nested case. - Spec edit without re-running
zbb generate— implementation will compile against stale types. Alwayszbb generateafter a spec change.
Source code
Promise<any>in anysrc/signature — use the generated types from../generated/api/*and../generated/model/*.process.envaccess insrc/— credentials and config flow throughConnectionProfile. The only place that may readprocess.envistest/e2e/constants.ts.- Relative imports missing
.jsextension — ESM undermodule: NodeNextrejects them.
Tests
jest.mock,sinon,fetch-mock, ormswanywhere — nock is the only mocking library.import nock from 'nock'(default import).test/integration/directory — that layout is gone. e2e tests live intest/e2e/and usedescribeModule<T>from@zerobias-org/module-test-client.- Hardcoded test values (IDs, orgs, repos) in
test/e2e/ortest/unit/— every env-driven value lives intest/e2e/constants.tswith a sensible default, and tests skip when empty. process.envoutsidetest/e2e/constants.ts— same rule as forsrc/, with the one designated exception.dotenvimport anywhere —zbb env setandzbb secret createmanage env state. The dependency is gone.- Skipped unit tests —
it.skip()/describe.skip()to dodge a problem is forbidden. Fix the impl or the mock. Suite-levelthis.skip()is reserved for e2e tests when a required env constant is empty. test/e2e/*.test.tswithoutCoreError.deserializeas the third arg todescribeModule— without it, errors thrown across the wire arrive as plain objects instead ofNotFoundErroretc.
Build / packaging
npm-shrinkwrap.jsonin the module directory — delete it. CI runsnpm ciagainstpackage-lock.json.gate-stamp.jsonmissing or stale at commit time — CI's only check iszbb gateCheckagainst the committed stamp. Runzbb gate --slot localand commit the result.- Module package not in
@zerobias-org/scope — module packages don't move. Products are@zerobias-org/product-*; modules are@zerobias-org/module-*. package.jsonmissing"type": "module"— the module is ESM. The generator sets this; never remove it.
Workflow scope
- Editing files outside the target module path — one module at a time.
package/<vendor>/[<suite>/]<service>/andgate-stamp.jsonare the only paths a module-scoped commit may touch. - Re-running the generator on an existing module to "fix" something — the generator throws when the destination exists, and rightly so. Edit the files in place.
Lifecycle
- Tests written but not run —
zbb testandzbb testDirectmust exit 0; for connectors,zbb testDockertoo. The stamp is the proof. - Build not run from cold before claiming completion —
zbb gate --slot localre-runs from cold. Anything green only in a warm daemon is suspect.
Signals you (or a user) shouldn't have to send
If you find yourself having to say any of these to an agent, the agent failed:
- "Now write tests"
- "Did you regenerate after editing the spec?"
- "Run
zbb lint" - "Commit the gate stamp"
- "Move that ID out of the test file"
- "Drop dotenv"
The right shape of a completion message is: "Gates 1–6 green. gate-stamp.json written and staged. PR-ready."
Gate ordering
Gates run in sequence. Don't skip ahead:
Gate 1: API spec → assembleSpec / bundleSpec
Gate 2: Type gen → generate*
Gate 3: Implementation → compile + lint
Gate 4: Test creation → unit + e2e files present
Gate 5: Test execution → zbb test / testDirect / testDocker
Gate 6: Build + stamp → zbb gate, gate-stamp.json committed
A failure at any gate is final until fixed. Gate N+1 doesn't run.
Related
- @.claude/skills/gate-api-spec/SKILL.md … @.claude/skills/gate-build/SKILL.md — checklists per gate
- @.claude/skills/completion-checklist/SKILL.md — the positive form of this file
- @.claude/skills/production-readiness/SKILL.md — extra checks before publish