Requirement Tracing

Requirement Tracing Skill

This skill describes how to write, link, and maintain requirements and design decisions in the Ankaios project.

Overview

Ankaios uses OpenFastTrace for bidirectional requirement tracing. Every feature must be traceable from its software design decision (swdd) through implementation and tests.

The tracing chain is:

swdd (requirement/design decision)
  ← impl (source code)
  ← utest (unit test)
  ← itest (integration test)
  ← stest (system test)

Requirement locations

Requirements and design decisions live in the SW design document of the crate they belong to:

Requirement format

Each requirement is a Markdown section with this structure:

#### Human-readable title
`swdd~<crate-prefix>-<descriptive-name>~<version>`

Status: approved

[When <condition separated by and>,] <object> shall <do something>.

Comment:
<Optional additional context.>

Rationale:
<Optional explanation of why this requirement exists.>

Tags:
- <UnitName>

Needs:
- impl
- utest

Wording rules

• Requirements shall use "shall" — never "should", "will", "is", etc.

• Only one object (subject) is allowed per requirement.

• Use the pattern: [When <condition>,] <object> shall <action>.

• When a requirement describes a sequence of actions by the same object, use one "shall" statement followed by an ordered list:

  When X happens, the server shall do Y by performing the following actions in order:
  
  1. First action
  2. Second action
  3. Third action

• When a requirement describes multiple independent behaviors, split into separate requirements.

• Attributes of a configurable entity can be listed:

  The server shall support configuring X with the following attributes:
  
  - `name` — description (required)
  - `prio` — description (optional, default `0`)

• Comment and Rationale sections are optional; omit them only when the reason is obvious and the rationale would not add new information. In all other cases, include a Rationale.

• Avoid term shadowing: do not reuse a term in a different requirement with a different meaning. For example, if "veto" means rejecting an entire state update, do not use "vetoed workloads" to describe individual workloads dropped from a list.

ID naming conventions

• Prefix with the crate/component: server-, agent-, cli-, grpc-, common-, ank-schema-
• Use lowercase kebab-case for the descriptive part
• Version starts at 1 and increments when the requirement text changes materially

Needs field

Specify which artifact types must cover this requirement:

Tags field

Tags reference the structural unit(s) (from the "Structural view" section of the swdesign doc) that implement this requirement. Use PascalCase unit names. Add tags to the Structural view in case new units are added with the implementation.

Design decisions

Design decisions use the same format but add the following fields between Rationale or Comment and Needs:

Assumptions:
<What was assumed to be true.>

Considered alternatives:
- **Alternative A**: <description and why rejected>
- **Alternative B**: <description and why rejected>

Linking implementation to requirements

In source code, add a tracing comment on the line(s) that implement the requirement:

// [impl->swdd~server-loads-startup-state-file~3]
fn load_startup_state(path: &Path) -> Result<State> {
    // ...
}

Rules:

• Place the comment directly above the line(s) that satisfy the requirement

• If the whole code in a .rs file implements the requirement, place the tracing anchor after the use statements

• One comment per requirement per logical block (don't repeat on every line)

• Multiple requirements can be traced from the same code block using separate comments:

  // [impl->swdd~server-validates-desired-state-api-version~1]
  // [impl->swdd~server-fails-on-invalid-startup-state~1]

Linking unit tests to requirements

In test functions, add a tracing comment directly above the test:

// [utest->swdd~server-loads-startup-state-file~3]
#[test]
fn test_loads_startup_state() {

    let result = load_startup_state(&path);
    assert!(result.is_ok());
}

If a test covers multiple requirements, add multiple comments.

Linking system tests to requirements

In Robot Framework .robot files, add a tracing comment above or inside the test case:

# [stest->swdd~server-loads-startup-state-file~3]
*** Test Cases ***
Server loads startup state from file
    [Documentation]    Verify server loads state from YAML file
    ...

When to write new requirements

Write a new requirement when:

• Implementing new user-visible behavior or a new feature
• Adding a new constraint or validation rule
• The behavior is not already described by an existing requirement

Write a new design decision when:

• Making a non-obvious architectural choice
• Choosing between multiple viable alternatives
• The decision has long-term implications or trade-offs