SolarosGo To Solaros
Documentation

Define Specifications

The Create stage is where features get their full behavioural definition. You organise approved features into feature sets, then define their use cases and requirements. This is where the specification takes shape.

Feature sets

Feature sets are logical groupings of related features - the components of your system. Create feature sets that represent natural boundaries in your product.

In the Reference Project, the Oven Project has feature sets like Clock Domains, User Features, Comms Protocol, and Memory Management. Some are system-level (common to most embedded products), others are product-specific.

To create a new feature set, use the categorisation page during Review stage and add a new feature set name. Feature set description can be added later. Then assign approved features to it.

A few principles for organising feature sets:

  • Group by system concern, not by team. "Power Management" is a better feature set than "Hardware Team's Features".
  • System-level sets in ALL CAPS. Following the convention in the Reference Project, feature sets like CLOCK DOMAINS or MEMORY MANAGEMENT signal system-level infrastructure.
  • Product-specific sets in Title Case. Sets like Gate Controller or Sensor Management signal product-specific behaviour.
  • Feature sets can be build components. Each set can be worked on independently, outsourced, or contracted as a unit. Clear and appropriate logical decomposition of ideas and functionality is key.

Use cases

Use cases are concrete scenarios for a feature. They describe what happens when the feature is used in a specific situation.

The happy path

The first use case for any feature should be the happy path - the scenario where everything goes right. The user takes an action, the system responds correctly, and the outcome is successful. No errors, no edge cases, no recovery.

Starting with the happy path gives you the baseline behaviour. Error handling and edge cases are separate use cases added later.

Adding use cases

With a feature selected in the Create view, add a use case with a name and description. The name should describe the scenario - "Gate locks successfully", "Temperature change accepted", "Sensor reading within range".

Each use case contains its own requirements (UCRs) that describe the step-by-step sequence for that scenario.

Feature requirements vs use case requirements

This is one of the most important distinctions in Specify.

Feature requirements (FRs) are general rules that apply to the feature regardless of which scenario is being executed. They define what must always be true.

Example for "Lock Gate":

  • "The gate lock shall only engage when the gate is in the fully closed position."
  • "While the gate lock is engaged, the system shall prevent motor activation."
Use case requirements (UCRs) are rules specific to one scenario. They describe what happens step by step in that particular use case.

Example for the "Gate locks successfully" happy path:

  • "When the user selects lock, the system shall verify the gate position."
  • "When position is confirmed as closed, the system shall engage the lock mechanism."
  • "When the lock is engaged, the system shall update the display to show locked status."
The distinction matters because FRs apply everywhere - they're the invariants of the feature. UCRs apply only within their scenario - they're the sequence of a specific flow.

In the Reference Project, expand User Features → Change Baking Temperature (F1) to see this in practice. The feature has general requirements about temperature ranges and session states, plus a happy path use case with step-by-step requirements.

Custom ordering

The order you create items in doesn't have to be the order they're read in. The Create stage supports:

Drag and drop - rearrange features, use cases, and requirements into the order that makes logical sense for your system. Engineers have arranged requirements in logical sequence (set → constrain → maintain) rather than creation order.

Arrow buttons - fine-tune ordering with single-step up/down controls.

Position numbers - a "Pos" column shows the current visual order.

Custom IDs - instead of just "UC1" or "FR2", you can use your own naming conventions like "INIT-001", "PWR-R-01", or "UC-2.1.1". Custom IDs must be unique within their scope (e.g., unique within a feature for use cases).

This flexibility means teams can match existing documentation conventions, use domain-specific prefixes, create hierarchical numbering schemes, and maintain consistency with external systems.

Writing good requirements

Requirements should be specific, testable, and written in platform-agnostic language. Not "respond quickly" but "respond within 100ms". Not "use a state machine" but "maintain temperature within ±1°C of target".

For detailed guidance on writing requirements, see Write Requirements and the EARS Reference.

Related

Need help? Contact us · Return to home