Find Code Names That Hide Side Effects

A function can work exactly as written and still cause bugs because its name lies about side effects, units, ownership, or failure behaviour. Callers trust the name before they read the implementation.

This guide belongs to reel R090. Comment NAMING for the matching module and runnable starter.

Define the boundary before building

Input: function names, field names, type definitions, call sites, side-effect traces, units, ownership rules, and public API constraints.

Output: a naming contract report, misleading names, hidden mutations, unit mismatches, compatibility risks, and rename plan.

The starter keeps exact checks in code and gives Claude only the reviewable drafting work. Dry-run is the default. Live mode can call Anthropic's Messages API, but it still returns a draft and performs no external action.

Paste this boundary into Claude Code before asking for implementation:

Workflow: Find Code Names That Hide Side Effects
Input: function names, field names, type definitions, call sites, side-effect traces, units, ownership rules, and public API constraints
Output: a naming contract report, misleading names, hidden mutations, unit mismatches, compatibility risks, and rename plan

Map the trigger, strict input fields, deterministic code checks, Claude drafting step, approval gate, failure queue, and saved evidence. Use null for missing facts. Do not change code or call an external service yet.

The modules that matter

Compare names with traces

Start at call sites. Record what data changes, which external calls run, what errors escape, and whether the function can be repeated. Then compare that evidence with the verb and return type.

Make contracts visible

Use read-shaped names for reads and command-shaped names for mutations. Put units in ambiguous fields, avoid inverted booleans, and name ownership when more than one actor can update a value.

Rename without breaking users

Add a compatibility alias, move internal callers, update docs and telemetry, warn old callers, then remove the alias on a named schedule. Do not change behaviour during the rename.

Rules worth keeping beside the code

Compare every name with observed behaviour at its call sites.
Use commands for mutations and queries for reads.
Put units and polarity in names when callers can confuse them.
Preserve public compatibility through an explicit migration plan.

The dangerous version is renaming public fields without a transition, changing behaviour during a naming cleanup, trusting comments over runtime evidence, or hiding writes behind read-shaped names. The pack deliberately stops at a draft so a person can inspect those boundaries before enabling anything real.

Test the ugly paths

Read-shaped function performs no writes.
Units survive round trips.
Old public name works during transition.
New and old paths return the same result.
Removal date and owner are recorded.

The final verification is concrete: Trace representative calls, assert their side effects, and run compatibility tests against old and new names before removing an alias.

Use this prompt to turn the evidence into acceptance tests:

Design tests for Find Code Names That Hide Side Effects using only the attached fictional fixtures.
Cover the normal path, missing input, malformed input, a repeated event, a permission failure, a dependency failure, and the named safety boundary.
For each test return: input, expected state, prohibited side effect, and evidence to save.
Do not execute external actions.

Run the pack locally

The ZIP is a complete Node 22 starter with no third-party npm dependency. It includes an importable n8n webhook, Docker Compose, GitHub Actions validation and manual-run workflows, deterministic samples, and tests.

npm test
npm run validate
npm run sample
cp .env.example .env
docker compose up --build

Only set WORKFLOW_MODE=live, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL after the dry-run output and tests make sense for your system. Keep real secrets in the environment, never in the n8n export.

Download the runnable pack

Start with the fictional dry-run. It validates the input and returns a reviewable draft without changing code, production data, customer accounts, or an external service.

Before enabling a real action

Replace every fictional fixture, assign the approval owner, define the duplicate key, set a timeout and retry rule, and save the original evidence. Then test one failure on purpose. If the workflow cannot stop visibly and replay safely, it is not ready to act.