Glossary

Core Concepts

System Definition - The complete, structured description of what a product does and how it behaves. In Specify, this is the collection of all feature sets, features, use cases, and requirements for a project. It serves as the single source of truth, the record of intent, and the IP that defines the product.

Record of Intent - The system definition captures not just what the system does, but what it was designed to do. This becomes the contractual basis for deliveries and the benchmark for validation and acceptance testing.

Knowledge Base - The accumulated system definition for a product. When people leave the team, the knowledge stays. New team members onboard by reading the feature hierarchy rather than reverse-engineering code.

Structure

Feature Set - A logical grouping of related features. Feature sets represent the components of your system. In the Reference Project, feature sets in ALL CAPS (CLOCK DOMAINS, MEMORY MANAGEMENT) are system-level concerns common to most embedded products. Feature sets in Title Case (Oven Control, User Features) are product-specific.

Feature - A bounded behavioural capability. Not a work item, not a user story, not a backlog entry. A feature in Specify is any capability, constraint or resource provisioning that needs to be defined - user interface interactions, communications protocols, background processes, memory management, diagnostic interventions, or control software.

Use Case - A concrete scenario for a feature. The most common is the "happy path" - the scenario where everything goes right and the outcome is successful. Additional use cases cover error conditions, edge cases, and alternative flows.

Feature Requirement (FR) - A general rule that governs a feature regardless of which scenario is being executed. For example, "Temperature changes are only permitted during an active baking session" applies whether the user is raising or lowering the temperature.

Use Case Requirement (UCR) - A rule specific to one scenario. For example, in the happy path for "Change Baking Temperature", a UCR might be "The display updates to show the new temperature within 200ms of the dial being turned." UCRs describe the step-by-step sequence within a use case.

Workflow

Plan - The first stage. Features are captured with a name and description. This is quick capture - progressive refinement means you don't need complete information to start. Features get P-numbers (P1, P2, P3) as planning identifiers.

Review - The second stage. Features are nominated for review, then prioritised (MoSCoW), categorised (metadata assigned), and either approved, rejected, or held. Approved features get F-numbers (F1, F2, F3) as permanent identifiers.

Create - The third stage. Approved features are organised into feature sets. Use cases and requirements are added. Custom ordering and custom IDs can be applied. This is where the full behavioural definition is built.

Finalise - The fourth stage. Features are reviewed for completeness, signed off, and locked. The specification can be exported as JSON, CSV, or PDF for downstream use.

Planning Number (P-number) - A temporary identifier (P1, P2, P3) assigned to features during the Plan stage. P-numbers track features before they've been approved.

Feature Number (F-number) - A permanent identifier (F1, F2, F3) assigned when a feature is approved in the Review stage. F-numbers are stable - F7 is always F7, even if the feature is moved between feature sets.

Prioritisation and Categorisation

MoSCoW - A prioritisation method with four levels: Must Have (non-negotiable, product unacceptable without it), Should Have (important but can defer), Could Have (nice to have, first to be deprioritised), and Won't Have (explicitly out of scope for this release). Guideline: Must Haves should be 60% or less of total requirements.

Feature Category - The type of behaviour a feature represents. Common categories include Feature Dialogue, Event Processing, State Handler, Device Configuration, and Hardware-Software Interface.

Feature Dialogue - A feature that defines an interaction between the user (or a protocol) and the system. These are the conversations your system has - a user pressing buttons, a protocol exchanging messages.

Event Processing - A feature that defines how the system handles events. Events can be scheduled (run at a specific time or frequency) or triggered (respond to an external signal). Event processing features often involve virtual state machines.

State Handler - A feature that manages a system state or mode. State handlers define what the system does while in a particular state and what causes transitions between states.

Device Configuration - A feature that defines hardware configuration or setup. These typically live in feature sets like Firmware Assumptions or Hardware Assumptions.

HW/SW Interface - A feature that defines the boundary between hardware and firmware. These make explicit the assumptions each side makes about the other - timing constraints, signal levels, resource availability.

Service Type - A classification of the implementation pattern a feature follows. Examples: Hardware Timing, Event Scheduled VSM, Feature Service.

Service Name - The logical component a feature belongs to. Often matches the feature set name. Used for traceability, component-level organisation and inclusion in the code construction process.

Ordering and Identity

Custom Order ID - A user-defined identifier for features, use cases, or requirements in the Create stage. Instead of just UC1 or FR2, teams can use their own conventions like "INIT-001", "PWR-R-01", or "UC-2.1.1". Must be unique within scope.

Specified Order - The position of an item within its parent, set via drag-and-drop or arrow buttons. The order is preserved through to export and the Finalise stage. Items have a "Pos" column showing their current visual position.

Unique Identity - A system-generated identifier (UC7, FR35, UCR12) that is globally unique within a project. Unlike custom order IDs which are user-defined, unique identities are stable and never change - even if the item is moved between features or feature sets.

Workflow States

Draft - The feature has been written but hasn't entered review. The text is a starting point and may need refinement.

Nominated - The feature has been put forward for review by the team.

Approved - The feature has been reviewed and confirmed as necessary for the project. Approved features are locked - only authorised users can unlock them for changes.

Categorised - All metadata has been set on the feature: MoSCoW priority, feature category, service type, service name, and feature set assignment.

Finalised - The feature's specification is complete, signed off, and locked for export. This is the terminal state.

Signoff - The formal approval of a feature's complete specification. Signoff means the feature is ready for implementation.

Review Assignment - A reviewer is assigned to a feature during the Review stage. The reviewer is responsible for assessing the feature's priority, categorisation, and readiness for approval.

Methodology

EARS - Easy Approach to Requirements Syntax. A set of patterns for writing clear, testable requirements. The five core patterns are Ubiquitous (always true), Event-Driven (triggered by event), State-Driven (condition persists), Optional Feature (feature-dependent), and Unwanted Behaviour (error handling). See the EARS Reference for the full pattern set.

Features First - The approach Specify follows. Describe the system as a collection of features grouped by feature set, rather than starting with a flat list of requirements. This creates natural traceability and allows architecture to emerge from feature boundaries rather than being guessed upfront.