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.
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."
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.
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 a 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 forms.
If the state is waiting for something to happen then the state name should be in the future tense forms.
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".
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.