revertwtf-catalog-entry

name	revertwtf-catalog-entry
description	Add or update precise revert.wtf catalog entries, fixtures, source metadata, and matcher tests for one or a small set of EVM/RPC/provider/wallet/protocol errors.
version	0.1.0

revert.wtf Catalog Entry Skill

Use this skill when the task is to add, fix, rename, deprecate, or verify specific entries in the revert.wtf error catalog.

Ground Rules

• Treat packages/catalog/src/data/shards/ as the source of truth.
• Keep source IDs stable. Put display names, aliases, lifecycle labels, legacy/sunsetting/renamed notes, and source references in packages/catalog/src/sources.ts.
• Keep catalog, parser, MCP, CLI, and web result paths package-owned and reproducible.
• Prefer narrow evidence over broad matching. Avoid plain substrings for generated custom errors when a selector exists.
• Use requires for guard context, especially broad JSON-RPC codes like -32000 or generic provider messages.

Workflow

1. Inspect the raw error and classify it:
   • layer: evm, rpc, provider, wallet, library, account_abstraction, protocol, or unknown.
   • source: ecosystem/library/provider/protocol id.
   • category: stable free-form bucket such as revert, json_rpc, gas_estimation, facilitator_verify, or signature.
2. Choose the shard:
   • Core standards/providers go under packages/catalog/src/data/shards/core/.
   • Protocol/app/ecosystem contracts go under packages/catalog/src/data/shards/ecosystems/.
3. Add a CatalogEntry with:
   • globally unique kebab-case id
   • human title
   • tight patterns
   • concise summary
   • concrete likelyCauses
   • action-oriented nextSteps
   • honest retryHelpful, increasingGasHelpful, and confidence
   • source-backed references
4. Add or update fixtures under fixtures/<layer-or-source>/ when practical.
5. Add parser or catalog tests when behavior could regress.

Pattern Choices

• Use selector for known custom error selectors.
• Use json_path for structured provider/MCP/facilitator fields such as code, status, invalidReason, or errorReason.
• Use aa_code for ERC-4337 AAxx codes.
• Use exact regexes for revert reason strings generated from source code.
• Use broad substrings only when the phrase is distinctive enough across the whole catalog.

Verification

Run the smallest useful set:

node scripts/build-catalog-data.mjs --generate --dist --check
node --experimental-strip-types scripts/validate-catalog.ts
node scripts/check-catalog-duplicates.mjs --fail-on=id,same-source-selector
node node_modules/typescript/bin/tsc -p packages/catalog/tsconfig.json --noEmit
node node_modules/typescript/bin/tsc -p packages/parser/tsconfig.json --noEmit

If the change touches parser behavior, also run parser tests when the local environment allows it:

pnpm --filter @revertwtf/parser test

On this Windows workspace, recursive pnpm/Vitest or Next commands may fail with spawn EPERM. If that happens, fall back to direct tsc and targeted Node smoke checks, and report the limitation.