← the whole session plugin/skills/how-to-name-things/SKILL.md

Guidelines for naming variables, test descriptions, and admin UI surfaces.

How to Name Things

Variable Names ARE the UX Contract (pre-commit CHECK 6)

Agents treat variable names as semantic ground truth. status = 'active' has ~200 possible meanings — agents pick one and cascade wrong logic. stripeSubscriptionStatus = 'active' has exactly one.

Banned bare words in const/let/var declarations

status, trial, type, data, result, value, item, flag, state, mode, level, tier, plan, role, access, config, options, info, details, response, error, count, list, active, enabled, current

Examples

Bad Good Why
const status = user.subscriptionStatus const stripeSubscriptionStatus = user.subscriptionStatus Agent doesn't know which status
const trial = isUserOnTrial() const isOnLegacyTrial = isUserOnLegacyTrial() Two trial systems exist (legacy vs cc_trial)
const type = session.type const coachingSessionType = session.type type could mean anything
const data = await fetch(...) const userProfilePayload = await fetch(...) Agent can't infer shape from data
const { status, type } = res const { status: subscriptionStatus, type: webhookEventType } = res Destructure with alias
const active = sub.status === 'active' const isSubscriptionActive = sub.status === 'active' Boolean needs domain prefix
const access = getTier() const effectiveProvisionedAccessTier = getTier() Tier of what? For whom?

Exemptions

  • Loop variables: items.map(item => ...) is fine — the scope is one line
  • Library imports: const { data } = useQuery(...) — can't control the API. Alias if used beyond the immediate line: const { data: coachingHistory } = useQuery(...)
  • Override: // @naming-exempt: <reason> suppresses the pre-commit check

The test

If an agent reading ONLY the variable name — no surrounding code — could hallucinate a second valid meaning, the name is wrong.

Test Descriptions — Agent-Facing Failure Contracts (pre-commit CHECK 7)

When a test fails, agents read ONLY the description in jest output to decide what broke. tier L20 for score < 40 forces the agent to hallucinate what L20 means. assigns LIMITED_ACCESS coaching tier when engagementScore below 40 — user sees basic prompts only tells it exactly what to fix.

Pattern

'{verb} {precise outcome} when {precise condition} — {UX consequence}'

Examples

Bad Good
'tier L20 for score < 40' 'assigns LIMITED_ACCESS coaching tier when engagementScore below 40 — user sees basic prompts only'
'returns correct payload' 'returns userProfile with subscriptionStatus and accessTier when authenticated — dashboard renders user state'
'handles error' 'returns 401 with SESSION_EXPIRED code when JWT is expired — client redirects to login'
'works properly' 'creates guest user with FREE_ACCESS tier when no auth cookie — coaching session starts immediately'
'test subscription' 'upgrades accessTier from FREE to MAX when Stripe webhook confirms payment — user gains full coaching access'

Banned vague words in it()/test() strings

correct, proper, appropriate, right, good, bad, works, handles, basic, simple, various, properly, correctly

describe() blocks

Name the UX domain being protected, not the function being called:

Bad Good
describe('calculateTier()') describe('Coaching tier assignment based on engagement score')
describe('authMiddleware') describe('Request authentication and access gating')
describe('stripeWebhook') describe('Subscription lifecycle state transitions from Stripe events')

The test

If an agent seeing ONLY the test name in failure output can't determine: (1) what broke, (2) for which user state, and (3) what UX consequence follows — the description is wrong.

Admin UI Tool Naming — humanUxTitle and humanUxSubtitle

When to Use

When adding humanUxTitle and humanUxSubtitle to any entry in a tool registry (see /how-to-bulk-register-atomic-tools if you have that skill). These fields translate agent-readable tool descriptions into human-readable capability statements for whoever reviews the registry in an admin UI.

A note on the examples below: most of them are drawn from one real product — a subscription coaching app with Stripe billing, ad-spend forecasting, and two internal tools named "Forecasting Workbench" and "Conversion Insights." They're kept concrete because a real before/after teaches the pattern better than a generic one, but they're one person's product, not a template to copy literally. Swap in your own tool names, your own data sources, your own domain — the rules themselves (below) are what to keep.

The Two Fields

  • humanUxTitle — What the admin GETS from this tool. The capability, stated as an outcome.
  • humanUxSubtitle — What it actually does, explained like you're telling someone. Specific enough that the admin recalls exactly why this exists.

The Rules (Learned Through Iteration)

Rule 1: Title = What You GET, Not What It Does

The title is the outcome the admin receives. Not the technical action, not the marketing pitch.

Wrong (describes the action):

"Query the Full Forecasting Analytics Engine"

Wrong (marketing fluff):

"How Each Segment Is Performing and Where It's Heading"

Right (what you GET):

"Get Deterministic Forecasting Metrics by Segment"

The admin reads this and knows: I get deterministic metrics, by segment. That's the capability.

Rule 2: Title Verb Should Match the Tool's Nature

  • GET endpoints → "Get ..."
  • POST that saves → "Save ..."
  • DELETE → "Remove ..."
  • Search/query → "Scan ..." or "Search ..."
  • Skills/workflows → "Create ...", "Run ...", "Build ..."
  • Simulators → "Simulate ..."

Rule 3: Subtitle = What It Does + What Makes It Specific

The subtitle must:

  1. State what it actually does in plain language
  2. Include what makes THIS tool specifically valuable (not generic features)
  3. Ground it in real places — name the admin tool, the page path, the data source
  4. Read like you're explaining it to someone, not selling it

Wrong (marketing with reasons):

"Month-by-month projections on revenue, conversions, and ad spend broken by audience segment — so you can see what's working before you commit budget"

Problems: "so you can..." is selling. And the content itself is vague — what projections? From where?

Wrong (feature list without grounding):

"Persist any insight from a segment comparison — with validation status, comments, and version history — restorable even after deletion"

Problem: Lists sub-features but never says WHERE it saves to. Where is the data going?

Right (specific, grounded, plain language):

"Auditable KPI breakdowns in the Forecasting Workbench sourced directly from raw Stripe receipts and Facebook Ads spend — real transactions, not estimates"

This works because: it names the tool (Forecasting Workbench), names the data sources (raw Stripe receipts, Facebook Ads spend), and states what's special (deterministic/auditable, not estimates).

Right (grounded in real UX flow):

"Save any segment finding instantly from the Forecasting Workbench to your Conversion Insights tool — with comments, validation, and full restore"

Pattern: save any X from Y to your Z — then supporting details after.

Rule 4: No Marketing, No "So You Can..."

Never add justification or motivation. The admin knows why they'd use it — just tell them what it is.

Wrong: "...so you can see what's working before you commit budget" Wrong: "...the first check when someone says they paid but can't get in" Right: Just describe the output and its source. The admin will connect the dots.

Rule 5: Name the Specific Thing That Makes It Special

Every tool has something that makes it not just another endpoint. Find it and lead with it.

  • Forecasting endpoints → deterministic, sourced from raw Stripe receipts and direct FB spend
  • Conversion insights → saves FROM the workbench TO a persistent tool
  • Artifact endpoints → 5-digit ID trace back to agent research
  • Stripe user lookup → formatted readable breakdown from raw Stripe data
  • Raw Stripe endpoint → unprocessed, every field as Stripe stores it

Rule 6: Subtitle Explains Like You're Telling Someone

Read it out loud. Does it sound like a human explaining what this does? Or does it sound like a spec sheet?

Spec sheet (wrong):

"Segment breakdowns, impact predictions, KPI audits, and spend tracking — every query powering the forecasting grid"

Telling someone (right):

"Get near-instant insights on the intent behind any of your company's systems or strategic decisions"

The Canonical Examples

Generic Example: A registry search over your own decisions

The pattern applies to any domain. Whatever your product is, if you keep a record of why decisions were made (a strategy doc, a decision log, a roadmap), a tool that searches it names the outcome, not the mechanism:

{
  "humanUxTitle": "Scan All Known Company Intent",
  "humanUxSubtitle": "Get near-instant insights on the intent behind any of your company's systems or strategic decisions"
}

Examples from one real setup (opt-in reference — replace with your own tools)

Forecasting Workbench Endpoints

{
  "humanUxTitle": "Get Deterministic Forecasting Metrics by Segment",
  "humanUxSubtitle": "Auditable KPI breakdowns in the Forecasting Workbench sourced directly from raw Stripe receipts and Facebook Ads spend — real transactions, not estimates"
}

Conversion Insights Endpoints

{
  "humanUxTitle": "Save and Restore Segment Comparison Findings",
  "humanUxSubtitle": "Save any segment finding instantly from the Forecasting Workbench to your Conversion Insights tool — with comments, validation, and full restore"
}

Artifact Endpoints

{
  "humanUxTitle": "Get the Full Audit Trail Behind Any Forecasting Number",
  "humanUxSubtitle": "Trace any KPI in the Forecasting Workbench back to the agent research document that produced it — retrieved by 5-digit artifact ID"
}

Stripe User Lookup (formatted)

{
  "humanUxTitle": "Get Any User's Stripe Billing Summary by Email",
  "humanUxSubtitle": "Pull any user's full Stripe account by email into a readable admin view — subscriptions, charges, trial status, payment methods, and invoices"
}

Stripe Customer Raw

{
  "humanUxTitle": "Get the Raw Stripe Customer Object by Email",
  "humanUxSubtitle": "Pull the complete unprocessed Stripe customer record by email — every field exactly as Stripe stores it, no formatting or filtering"
}

The Evolution (Why Each Wrong Version Was Wrong)

Still the same real setup (see note above) — kept because seeing the wrong versions, and specifically why each one was wrong, teaches the rules faster than the rules alone.

Attempt 1: Abstract "strategic promises" framing

Title: "Pull up any strategic promise you made and see if it's actually wired to the product"
Subtitle: "Every pricing rule, UX guarantee, and business commitment you locked in — traced to which screens enforce it and whether agents are honoring it"

Why wrong: "Strategic promise" is abstract jargon. The admin's reaction was "I don't get it. What's a strategic promise?" The tool gives agents semantic search on company intent — say THAT.

Attempt 2: Capability as action instead of outcome

Title: "Query the Full Forecasting Analytics Engine"

Why wrong: Title should be what you GET, not what you DO. "Query" is an action. "Get Deterministic Forecasting Metrics" is an outcome.

Attempt 3: Marketing fluff noun-stacking

Subtitle: "Segment breakdowns, impact predictions, KPI audits, and spend tracking — every query powering the forecasting grid"

Why wrong: Sounds like a marketing brochure. A pile of nouns stuffed together to sound important. Doesn't say what's actually special about this endpoint (deterministic data from real Stripe/FB sources).

Attempt 4: Adding "why you'd care" reasons

Subtitle: "Subscriptions, charges, trial status, payment methods — look up any user's Stripe account when they say something's wrong with their access"

Why wrong: "when they say something's wrong with their access" is selling you on why to use it. The admin already knows why. Just describe what it returns.

Attempt 5: Feature list without grounding

Subtitle: "Persist any insight from a segment comparison — with validation status, comments, and version history — restorable even after deletion"

Why wrong: Lists features (validation, comments, version history, restore) but never says WHERE it saves to. The fix: "Save any segment finding instantly from the Forecasting Workbench to your Conversion Insights tool" — names the source AND the destination.

Checklist Before Submitting

  • Does the title state what the admin GETS? (not what they DO)
  • Does the title verb match the tool type? (Get/Save/Scan/Simulate/etc.)
  • Does the subtitle explain it like telling someone?
  • Does the subtitle name specific things? (tools, pages, data sources — not generic nouns)
  • Does the subtitle state what's SPECIFICALLY special about this tool?
  • Is there zero "so you can..." or other motivation/justification?
  • Would the admin instantly know exactly what this does without clicking into it?
  • Is the subtitle grounded in real places where possible? (FROM x TO y)