Naming Conventions for Memo Preprocessing

Fragment

convention

Separator rules — critical

StarSpec uses two separators that must never be confused:

Separator	Used for	Example
`/`	Cross-document references	`domain/auth`, `feature/add-bookmark`
(none)	In-document child tag ids — plain kebab-case	`add-bookmark`, `bookmark-added`

Never write action:add-bookmark — type prefixes on ids are a validation error. The tag type ({% action %}) already provides the context. Never write domain:auth — that would be a type prefix. Cross-doc refs use /.

Format rules

All identifiers in a PreSpec use kebab-case — no type prefix, no camelCase, no PascalCase, no underscores.

Item	Format	Example
Action	`kebab-case`	`add-bookmark`
Event	`kebab-case`	`bookmark-added`
Operation	`kebab-case`	`get-bookmark`
Error	`kebab-case`	`bookmark-not-found`
Entity	`PascalCase` (name only, no prefix)	`BookmarkEntry`
Domain	`kebab-case`	`bookmark`
Feature	`kebab-case`	`add-bookmark`
Flow	`kebab-case`	`add-bookmark-flow`
Role	`kebab-case`	`admin-user`

Actions — imperative verb-noun

Actions represent commands: something a role requests of the system.

add-bookmark      ✓
remove-bookmark   ✓
lock-account      ✓
addBookmark       ✗  camelCase
AddBookmark       ✗  PascalCase
add_bookmark      ✗  underscores
action:add-bookmark ✗  type prefix (validation error)

Events — past-tense noun phrase

Events represent facts: something that already occurred.

bookmark-added     ✓
account-locked     ✓
session-expired    ✓
add-bookmark       ✗  imperative (that is an action)
bookmarkAdded      ✗  camelCase
event:bookmark-added ✗  type prefix (validation error)

Derivation rule: an event name is predictably derived from its triggering action by converting verb-noun → noun-verb(past):

add-bookmark   →  bookmark-added
lock-account   →  account-locked
expire-session →  session-expired

Operations — descriptive (read) or imperative (write)

Operations are system-internal and have no direct actor.

get-bookmark       ✓  (read)
search-bookmarks   ✓  (read, plural for collection)
create-bookmark    ✓  (write)
getBookmark        ✗  camelCase
operation:get-bookmark ✗  type prefix (validation error)

Errors — descriptive noun phrase

Errors represent a named domain failure mode.

bookmark-not-found       ✓
duplicate-url            ✓
insufficient-permissions ✓
notFound                 ✗  camelCase
error:404                ✗  HTTP code, not domain name
error:bookmark-not-found ✗  type prefix (validation error)

Coherence rule

When a feature, flow, action, and component all represent the same operation, the name must match across all of them:

feature/add-bookmark      ← document id
flow/add-bookmark         ← flow for this feature
add-bookmark              ← domain action name
bookmark-added            ← emitted outcome
bookmark-not-found        ← failure mode

Use the action name as the anchor. Derive everything else from it.

Common violations to catch during extraction

Violation	Example	Fix
camelCase	`addBookmark`	`add-bookmark`
PascalCase	`AddBookmark`	`add-bookmark`
Type prefix	`action:add-bookmark`	`add-bookmark`
Action in past tense	`bookmark-added` used as action name	use as event name instead
Event in imperative	`add-bookmark` used as event name	use as action name instead
HTTP-code error	`404`	`bookmark-not-found`
Ordinal id	`1` on a requirement	`save-url`