Semantic Naming Standards

Use names that encode the actual meaning and follow the project’s identifier contracts/conventions.

• Avoid vague booleans/flags: rename to what the value means, not what it excludes.
  • Bad: load(refresh, background)
  • Good: load(refresh, userInitiated)
• Don’t model domain states as booleans: if it’s really “seeded vs written vs …”, use a string union/enum (e.g. entry?: "run" | "continue").
• Keep shared names aligned with shared types/contracts: if there is a canonical type (e.g. ClientName), don’t invent parallel strings.
• Treat event/telemetry property keys as schema contracts: renaming taskId→ulid requires updating all call sites and auditing consumers that join on the old key.
• Name public APIs to reduce ambiguity: either expose one obvious entry point, or make the names clearly indicate which one to call (and add decisive comments if both must remain public).
• Apply casing conventions by identifier origin (when applicable): e.g. caller-supplied context keys use camelCase, while envelope/global-enrichment keys use snake_case.
• Eliminate magic values: extract important numeric timings into named constants and document their purpose.

Following these rules prevents “looks-like-it-compiles-but-is-wrong” naming drift and makes identifiers self-explanatory for future call sites.