1. Concepts
  2. Naming Conventions

Concepts

Naming Conventions

Key aspect of the Stubber Framework

Overview

Phil Karlton once said, "There are only two hard things in Computer Science: cache invalidation and naming things.".

Indeed we have found that to be true, so we have put together some guidelines to help you name things in Stubber.

Naming things is a key aspect of the Stubber Framework.
It is important to name things in a specific way to ensure the process can be followed by humans and AI alike.

NOTE

Strictly keeping to the naming conventions is the best way to ensure what you build in Stubber works well.

Naming Templates

The first thing that needs to be named is the template.
You should name the template that describes what you are modelling in Stubber. To name properly you should understand what the start and end of the process is.
The template should be named in the singular form. eg. Sales Enquiry

In order to check your name you should be able to say "There are 100 [template name] stubs in the system." So for example, "There are 100 Sales Enquiry stubs in the system."

TIP

Check the name of your template by saying out loud : "There are 100 [template name] stubs in the system."

Example : Sales Enquiry

  • Good: Sales Enquiry
  • Language Test: There are 100 Sales Enquiry stubs in the system.
  • Start: New sales enquiry with some details
  • End: Sales enquiry closed

Example : Website AI Conversation

If you are building an AI Agent process that will be active on a website via a webchat, you might name the template "Website Conversation".
You should think of what each stub will contain and what the start and end of the process is.

  • Good: Website Conversation
  • Language Test: There are 100 Website Conversation stubs in the system.
  • Start: User visits website and starts a conversation
  • End: User ends conversation

Example : Support Ticket

If you are building a process to manage support tickets, you might name the template "Support Ticket".

  • Good: Support Ticket
  • Language Test: There are 100 Support Ticket stubs in the system.
  • Start: New support ticket created
  • End: Support ticket closed

Example : Support Conversation

If you are building a support AI Agent process that will handle support for a product, you might name the template "Support Conversation".

  • Good: Support Conversation
  • Language Test: There are 100 Support Conversation stubs in the system.
  • Start: User starts conversation with support agent
  • End: User ends conversation

Naming States

The next thing that needs to be named correctly is the states of the process.
The state names are always in relation to the template.
If the template is called "Sales Enquiry" then the states should be named in relation to a sales enquiry.

TIP

States can start with :

  • awaiting-[something]
  • waiting-for-[something]

States can end with :

  • [something]-in-progress
  • [something]-active
  • [something]-pending

State Tenses

It is helpful to think about the state in terms of tense.

  • What is happening in the state? Is there work being done, or is it waiting for something to happen?
  • If there is work being done, then the state name should be in the present tense.
  • If the state is waiting for something to happen, then the state name should be in the future tense.

Present Tense State Names

All present tense state names end in -in-progress or -active.

Future Tense State Names

All future tense state names start with awaiting- or waiting-for, or end with -pending.

End State Names

The end state names should be in the past tense forms.

Language Test

You should be able to say "The [template name] stub is in the [state name] state."
You should be able to say "The state of the stub is [state name]."

Example : Sales Enquiry Starting State

  • Good: contact-pending
  • Tense: Future
  • Language Test: The sales enquiry is in the contact pending state.

Example : Sales Enquiry Proposal Drafting

Imagine a state where a sales enquiry is being worked on and a proposal is being drafted.

  • Good: proposal-drafting-in-progress
  • Tense: Present
  • Language Test: The sales enquiry is in the proposal drafting in progress state.

Example : AI Support Conversation Busy

Imagine a state where an AI Agent is busy with a conversation.

  • Good: conversation-in-progress
  • Tense: Present
  • Language Test: The support conversation is in the conversation in progress state.

Naming Actions

The last thing that needs to be named correctly is the actions of the process.
The action name should be a verb that describes what the action does in the state.
The action names are named from the perspective of the user or AI agent that would be responsible for the action in the state.
If the template is called "Sales Enquiry" and the state is called "proposal-drafting-in-progress" then the actions should be named to indicate to the sales person what they could do in that state, for example "send_proposal".

TIP

You should be able to say out loud "I want to [action name]."

Language Test

You should be able to put the words "I want to..." in front of the action name.
This should make sense in the context of the state.

Example : Sales Enquiry Proposal Drafting Actions

  • Good: send_proposal
  • Language Test: I want to send proposal.

Example : AI Support Conversation Actions

  • Good: escalate_to_human
  • Language Test: I want to escalate to human.
  • Good: close_conversation
  • Language Test: I want to close conversation.
  • Good: send_survey
  • Language Test: I want to send survey.
  • Good: run_diagnosis
  • Language Test: I want to run diagnosis.