Naming Conventions

Overview

ubFlow uses descriptive, human-readable IDs for all specification elements. Unlike traditional sequential numbering (e.g., REQ_001), descriptive IDs are self-documenting, grep-friendly, and eliminate the “insert pain” of numbered sequences.

Why Descriptive IDs?

Aspect

Sequential (NEED_CORE_001)

Descriptive (NEED_CORE_SPEC_AS_CODE)

Self-documenting

No — must look it up

Yes — readable inline

Insert new items

Renumber or use gaps

Just pick a name

Grep-friendly

Not really

grep SPEC_AS_CODE = instant

Link readability

:links: NEED_CORE_001 — opaque

:links: NEED_CORE_SPEC_AS_CODE — clear

Ordering bias

Implies priority/sequence

No false hierarchy

Duplicate safety

Manual tracking

sphinx-needs catches at build time

The only trade-off is length, but with short slugs (2–4 words) this is very manageable.

ID Format

<TYPE>_<THEME>_<SHORT_SLUG>

  • TYPE: The specification level prefix (NEED, REQ, SPEC)

  • THEME: Abbreviated domain/component identifier (2–5 chars)

  • SHORT_SLUG: Descriptive name in 2–4 words, UPPERCASE, underscores

Note: Although need types are now need, swreq, and swdesign (ASPICE aligned), ID prefixes are NEED_, REQ_, and SPEC_ for clarity and consistency.

Theme Abbreviations

Abbreviation

Full Name

Used at Levels

CORE

Core Methodology

NEED (need), REQ (swreq)

WF

Workflows

NEED (need), REQ (swreq)

CHG

Change Management

NEED (need), REQ (swreq)

TRACE

Traceability & Quality

NEED (need), REQ (swreq)

INST

Installation & Setup

NEED (need), REQ (swreq)

DX

Developer Experience

NEED (need), REQ (swreq)

REL

Release

NEED (need), REQ (swreq)

Level 2 (Software Detailed Design) uses component-based themes instead of domain themes:

Abbreviation

Full Name

Level

AGENT

Agent Architecture

SPEC (swdesign)

DOC

Documentation Structure

SPEC (swdesign)

INST

Installation Scripts

SPEC

REL

Release Process

SPEC

Examples by Level

Level 0 — Stakeholder Needs

NEED_CORE_SPEC_AS_CODE        # Core: manage specs as code
NEED_CHG_ANALYZE              # Change Mgmt: analyze changes
NEED_INST_BOOTSTRAP           # Installation: environment bootstrap
NEED_REL_CREATE               # Release: create a release
NEED_DX_PROJECT_MEMORY        # Dev Experience: maintain project memory

Level 1 — Software Requirements

REQ_CORE_SPHINX_NEEDS       # Core: requirements management with sphinx-needs
REQ_CHG_ANALYSIS_AGENT      # Change Mgmt: change analysis agent
REQ_INST_AUTO_SETUP         # Installation: automatic environment setup
REQ_REL_SEMVER              # Release: semantic versioning
REQ_TRACE_MECE              # Traceability: MECE review

Note: Uses swreq directive, REQ_ prefix.

Level 2 — Software Detailed Design

SPEC_AGENT_WORKFLOW         # Agent component: four-agent workflow
SPEC_DOC_STRUCTURE          # Documentation component: sphinx-needs structure
SPEC_INST_INIT_SCRIPTS      # Installation component: init scripts
SPEC_REL_VERSION_FORMAT     # Release component: version format

Note: Uses swdesign directive, SPEC_ prefix, component-based themes.

Slug Guidelines

  1. Keep slugs short: 2–4 words maximum

  2. Be specific: ANALYZE not DO_ANALYSIS_OF_CHANGES

  3. Use domain language: terms stakeholders recognize

  4. Avoid ambiguity: NEW_PROJECT vs ADOPT_EXISTING, not INSTALL_1 vs INSTALL_2

  5. ALL CAPS: NEED_CHG_ANALYZE not NEED_chg_analyze

  6. Underscores only: no hyphens, no dots

Cross-Level Consistency

The theme abbreviation in a requirement ID does not need to match the theme of the linked Stakeholder Need. Requirements follow the 1:1 file mapping with Stakeholder Needs (see Methodology: Specification Hierarchy & File Organization), but the slug describes the requirement, not the parent story.

.. swreq:: Change Analysis Agent
   :id: REQ_CHG_ANALYSIS_AGENT
   :links: NEED_CHG_ANALYZE

   .. (theme CHG matches because the REQ and NEED are in the same domain)

For Software Detailed Designs, the theme shifts to component names, so mismatches are expected and healthy:

.. swdesign:: Setup Agent Design
   :id: SPEC_INST_SETUP_AGENT
   :links: REQ_INST_NEW_PROJECT, REQ_INST_ADOPT_EXISTING, REQ_INST_SPHINX_NEEDS_DEP

   .. (SPEC theme is INST because it's an installation component,
       even though REQs come from multiple domains)

Uniqueness

sphinx-needs enforces global uniqueness across all .rst files at build time. If two items share an ID, the build fails with an explicit error. This makes descriptive IDs safer than sequential numbers (where duplicates across files are easy to create accidentally).

Migration from Sequential IDs

When renaming from sequential to descriptive IDs:

  1. Build a complete mapping table (old → new)

  2. Rename :id: directives in specification files

  3. Update all :links: directives referencing renamed IDs

  4. Update references in agent files, scripts, release notes

  5. Run sphinx-build to validate — it will catch any missed references