Core¶
Foundation of the ubFlow methodology — specifications as code, file organization, and traceability.
Last Updated: 2026-02-15
Level 0: Stakeholder Needs (WHY)¶
As a developer, I want to manage Stakeholder Needs, Requirements, and Specs in version-controlled RST files, so that I can branch, merge, review, and track the full specification hierarchy like code. Specification Hierarchy: ┌─────────────────────────────────────────────────────────────┐
│ Level 0: Stakeholder Needs (WHY) │
│ "As a user, I want X so that Y" │
└──────────────────────┬──────────────────────────────────────┘
│ derives
▼
┌─────────────────────────────────────────────────────────────┐
│ Level 1: Requirements (WHAT) │
│ "System SHALL do X" + Acceptance Criteria │
└──────────────────────┬──────────────────────────────────────┘
│ implements
▼
┌─────────────────────────────────────────────────────────────┐
│ Level 2: Design/Specs (HOW) │
│ Technical design, architecture, interfaces │
└─────────────────────────────────────────────────────────────┘
Acceptance Scenarios:
|
As a developer (or AI agent), I want to have a well-defined methodology for organizing specification files across levels (Stakeholder Needs, Requirements, Design), so that I can find, navigate, maintain, and scale specifications consistently as the project grows. Acceptance Scenarios:
|
Level 1: Requirements (WHAT)¶
Description: ubFlow SHALL manage requirements in sphinx-needs RST format. Rationale: sphinx-needs provides structured requirements with automatic traceability, validation, and documentation generation. Acceptance Criteria:
|
Description: ubFlow SHALL maintain design specifications linked to requirements. Rationale: Traceability from requirements to design ensures all requirements are addressed and design decisions are justified. Acceptance Criteria:
|
File Organization¶
Description: ubFlow SHALL organize specification files by domain type:
Rationale: Stakeholder Needs and Requirements answer “why” and “what” from the stakeholder perspective, so they group naturally by user goals. Design Specs answer “how” from the technical perspective, so they group by architectural component. A single design component may address requirements from multiple themes. Acceptance Criteria:
|
Description: ubFlow SHALL maintain a 1:1 correspondence between Level 0 (Stakeholder Need) and Level 1 (Requirement) files. Rationale:
A Stakeholder Need file defines a bounded context. Its requirements are cohesive
and belong together. The 1:1 mapping provides a simple mental model:
“Where are the REQs for this NEED file? In the matching Acceptance Criteria:
|
Level 2: Design (HOW)¶
Design: Documentation organized thematically in a flat module structure with combined US/REQ/SPEC content per theme. Directory Structure: docs/
├── conf.py # sphinx-needs configuration
├── index.rst # Main index
├── methodology.rst # File organization guide
├── namingconventions.rst # ID naming conventions
├── quickstart.rst # Getting started guide
├── workflows.rst # Workflow documentation
├── releasenotes.rst # Release history
├── modules/ # Thematic specifications
│ ├── installation.rst # Installation theme
│ ├── changemanagement.rst # Change management theme
│ ├── release.rst # Release 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/
└── index.rst # Auto-generated traceability matrices
Naming Conventions:
See [docs/namingconventions.rst](../namingconventions.rst) for full convention. File Organization by Domain Type: Each module file contains related NEED + REQ + SPEC organized by theme. This provides natural thematic grouping while maintaining full traceability.
This structure provides thematic cohesion while preserving the three-level hierarchy within each file. |
Traceability¶
Stakeholder Needs¶
ID |
Title |
Status |
Priority |
|---|---|---|---|
Consistent File Organization Across Specification Levels |
implemented |
high |
|
Manage Specifications as Code |
implemented |
mandatory |
Requirements¶
ID |
Title |
Status |
Tags |
|---|---|---|---|
File Organization by Domain Type |
implemented |
core; methodology; organization |
|
Level 1 Mirrors Level 0 File Structure |
approved |
core; methodology; organization |
|
Requirements Management with sphinx-needs |
implemented |
core; sphinx-needs |
|
Design Specification with Traceability |
implemented |
core; traceability |
Design Specifications¶
ID |
Title |
Status |
Links |
|---|---|---|---|
sphinx-needs Documentation Structure |
approved |
REQ_CORE_SPHINX_NEEDS; REQ_CORE_TRACEABILITY; REQ_CORE_DOMAIN_ORG; REQ_CORE_L1_MIRROR |