Methodology: Specification Hierarchy & File Organization

Overview

ubFlow uses a three-level specification hierarchy based on sphinx-needs traceability. Each level answers a different question and serves a different audience. This methodology defines how specifications are structured, split into files, and traced across levels.

The Three Levels

Level 0: Stakeholder Needs  (WHY)   → Stakeholder perspective
         │ :links:
         ▼
Level 1: SW Requirements    (WHAT)  → Software behavior
         │ :links:
         ▼
Level 2: SW Detailed Design (HOW)   → Technical solution

Level

Question

Audience

ID Prefix

Location

0

Why does this matter?

Stakeholders, Product Owner

NEED_

docs/modules/<theme>.rst

1

What must the software do?

Architects, Reviewers

REQ_

docs/modules/<theme>.rst

2

How is it designed in detail?

Developers, AI Agents

SPEC_

docs/modules/<theme>.rst

File Organization Principles

Thematic Organization

ubFlow organizes specifications by theme — each module file contains all three levels (NEED + REQ + SPEC) for one cohesive topic area. This provides thematic cohesion while maintaining the three-level hierarchy within each file.

Key principle: Related specifications stay together. A developer working on “installation” sees the full picture (WHY → WHAT → HOW) in one file, not spread across three directories.

Module Files: Themed Specifications

Each module file groups specifications by stakeholder theme or technical domain.

Splitting criteria:

  • One file per coherent theme or domain area

  • Contains all three levels (NEED + REQ + SPEC) for that theme

  • Typical file contains 2–8 Stakeholder Needs, 5–20 SW Requirements, 5–15 SW Detailed Designs

  • Sections clearly separated: “Level 0: Stakeholder Needs (WHY)”, “Level 1: Software Requirements (WHAT)”, “Level 2: Software Detailed Design (HOW)”

Example modules:

File

Scope

installation.rst

Bootstrap, setup, init scripts, auto-detection, distribution

release.rst

Versioning, updates, validation, GitHub releases, CI/CD

changemanagement.rst

Change workflow, agents (change/implement/verify), analysis

traceability.rst

Link discovery, MECE review, vertical tracing, quality checks

workflows.rst

End-to-end workflows, agent orchestration, handoffs

core.rst

Core methodology, specifications as code, file organization

devexperience.rst

Developer experience, memory agent, agent interaction patterns

Guideline: When identifying themes, ask “What coherent topic does this address?” Group related Stakeholder Needs, their SW Requirements, and the Detailed Designs that implement them.

Cross-File Traceability

sphinx-needs resolves :links: directives across all files in the Sphinx project. Splitting specifications into multiple files has no impact on traceability. The needtable, needflow, and needmatrix directives aggregate from all sources.

.. req:: Bootstrap Validation
   :id: REQ_INST_BOOTSTRAP_VALIDATION
   :status: draft
   :links: NEED_INST_BOOTSTRAP

docs/
├── conf.py                      # Sphinx configuration
├── index.rst                    # Main documentation index
├── methodology.rst              # This file (organization guide)
├── namingconventions.rst        # ID naming conventions
├── quickstart.rst               # Getting started guide
├── workflows.rst                # Workflow documentation
├── releasenotes.rst             # Release history
├── modules/                     # Thematic specifications (NEED + REQ + SPEC)
│   ├── installation.rst         # Installation & setup theme
│   ├── release.rst              # Release & versioning theme
│   ├── changemanagement.rst     # Change workflow theme
│   ├── traceability.rst         # Quality & traceability theme
│   ├── workflows.rst            # Workflow orchestration theme
│   ├── core.rst                 # Core methodology theme
│   └── devexperience.rst        # Developer experience theme
├── changes/                     # Change Documents (deleted after release)
└── 31_traceability/             # Auto-generated traceability matrices
    └── index.rst

Each module file follows this structure:

==================
Module Title
==================

Brief description.

**Last Updated**: YYYY-MM-DD

.. contents:: Contents
   :depth: 2
   :local:


Level 0: Stakeholder Needs (WHY)
==================================

.. need:: Stakeholder Need Title
   :id: NEED_THEME_SLUG
   :status: implemented
   :priority: mandatory
   :tags: theme, ...
   :links: ...

   ...


Level 1: Software Requirements (WHAT)
======================================

.. swreq:: Requirement Title
   :id: REQ_THEME_SLUG
   :status: implemented
   :priority: mandatory
   :tags: theme, ...
   :links: NEED_THEME_SLUG

.. needtable::
   :filter: id.startswith('NEED_THEME') or id.startswith('REQ_THEME') or id.startswith('SPEC_COMPONENT')

Scaling Guidelines

Scale

Module Files

Per-Module Content

Small (< 10 NEEDs)

3–5 module files

2–5 NEED + 5–10 REQ + 3–8 SPEC each

Medium (10–50 NEEDs)

5–10 module files

3–8 NEED + 8–15 REQ + 5–12 SPEC each

Large (50+ NEEDs)

10–15 module files

5–10 NEED + 10–20 REQ + 8–15 SPEC each

When to split an existing module:

  • More than ~10 Stakeholder Needs in one file

  • More than ~20 SW Requirements in one file

  • More than ~15 SW Detailed Designs in one file

  • When two clearly distinct themes share a file

  • File exceeds ~1000 lines of RST

When NOT to split:

  • Fewer than 3 Stakeholder Needs — keep in a shared file

  • Items are tightly cohesive and always reviewed together

  • Splitting would create artificial boundaries between related specs

Naming Conventions

File and ID naming conventions are documented in Naming Conventions.

File naming summary:

Pattern

Grouping Principle

<theme>.rst

Thematic module (NEED + REQ + SPEC together)

The <theme> name should be short, lowercase, and use no underscores: installation, release, changemanagement, traceability, workflows, core, devexperience.

ID naming: ubFlow uses descriptive IDs (e.g., NEED_CORE_SPEC_AS_CODE) instead of sequential numbers. The ID prefix indicates the level (NEED/REQ/SPEC), followed by theme abbreviation, followed by descriptive slug.

See Naming Conventions for the full convention.

Summary

The fundamental insight of this methodology:

Levels 0–1 organize by problem domain (user goals). Level 2 organizes by solution domain (technical components). This asymmetry is intentional — it reflects the natural boundary where stakeholder needs meet system architecture.

sphinx-needs traceability links bridge this boundary, maintaining full visibility from Thematic organization keeps related specifications together. A developer working on one topic sees the full picture (WHY → WHAT → HOW) in one place, not spread across multiple files or directories.

sphinx-needs traceability links work seamlessly across all module files, maintaining full visibility from Stakeholder Needs through SW Requirements to Detailed Design — regardless of file organization