SRS Authoring Guide

1. Overview

SRS (Software Requirements Specification) documents define what the system shall do -- the externally observable behaviors that are independently testable and traceable to source material. They deliberately exclude implementation details, UI styling, and configuration choices, which are captured elsewhere.

The SRS corpus consists of three kinds of files:

Kind	Count	Location	Description
Domain files	29	docusaurus/docs/srs/*.md	Functional areas (e.g., Filters, Kit Configuration, Audit Log)
Rule files	61	docusaurus/docs/srs/rules/rule-*.md	Analysis rules (e.g., AMB, Threshold, Westgard)
Introduction	1	docusaurus/docs/srs/introduction.md	Landing page and document index

Definitive Format Examples

Before writing or modifying any SRS file, study these real v3.0.0 files:

Purpose	File	Why
Small, clean domain	srs/filters.md	Single REQ, complete sections, good consolidation notes
Complete rule pattern	srs/rules/rule-amb.md	Rule summary, flowchart with styled nodes, resolution code mapping
Large domain	srs/kitcfg.md	Multiple REQs, grouped headings, extensive ACs, import/export patterns

These files are the authoritative format reference. When in doubt about structure, consult them rather than this guide.

---

2. Classification Taxonomy

Every extracted item must be classified into exactly one of five categories. Hybrid classifications are prohibited.

2.1 The Five Categories

REQUIREMENT

An independently testable, externally observable system behavior expressed with normative language ("shall").

A Requirement describes what the system does, not how it looks or how it is configured. It must be testable in isolation -- if you cannot write a test for it without also testing something else, it is not a Requirement.

Examples from real files:

• "The system shall allow users to constrain displayed data using filter criteria." (REQ-FILTERS-001)
• "The system shall assign the CLASSIFICATION problem to observations with ambiguous classification when the AMB rule is executed during run import." (REQ-RULES-AMB-001)

ACCEPTANCE_CRITERIA

Conditions that validate a Requirement without introducing new behavior. Testable only in the context of their parent Requirement.

ACs describe observable outcomes. They may cover sorting, filtering, pagination, validation rules, or visual indicators when these do not alter system capability.

Examples:

• "Multiple filter criteria may be combined (AND logic)" -- validates REQ-FILTERS-001
• "The system shall set observation final_cls to Positive when resolution code AMB,SETPOS is applied" -- validates REQ-RULES-AMB-003

REFINEMENT

A constraint or qualification of a Requirement that does not change its fundamental behavior.

Refinements describe variants, operational contexts, or scope limitations. They cannot stand alone as Requirements and must not introduce new behavior.

Examples:

• Single-site vs. multi-site operation modes
• Mode-specific behavior (e.g., "when quantitative mode is enabled")
• Conditional applicability (e.g., "applies only to IC targets")

UI_DETAIL

Presentation, layout, or interaction mechanics. UI Details are not independently testable and must never be promoted to Requirements.

Examples:

• "Calendar picker displaying one month at a time" (filters.md UI Notes)
• "AMB observations are flagged in red" (rule-amb.md UI Notes)
• Tab layout, icon placement, tooltip styling, button alignment

CONFIG_OPTION

A selectable system setting that alters behavior within the bounds of a Requirement. Configuration Options are client- or deployment-specific and must not be promoted to Requirements.

Examples:

• default_text_match_mode: prefix (filters.md Configuration Options)
• preferred_provider: dxai (rule-amb.md Configuration Options)

2.2 Decision Key

The single deciding question: "Is this independently testable system behavior?"

2.3 Prohibited Patterns

The following patterns are explicitly prohibited by the Phase 0 Semantic Lock Specification. Any detected prohibited pattern must be fixed before proceeding.

#	Prohibited Pattern	Example of Violation	Correct Alternative
1	Promoting UI behaviors to standalone Requirements	"REQ-001: The system shall display a sticky header"	Demote to UI_DETAIL in Notes section
2	Requirements that exist solely due to UI widgets	"REQ-002: The system shall show a calendar picker"	Move to UI Notes (Illustrative)
3	Splitting a single report by presentation differences	"REQ-003: PDF report" + "REQ-004: Excel report" as separate REQs	Single REQ with export format as AC
4	Third-level headings beneath Requirements	#### Sub-section under a REQ heading	Use italic sub-headers in AC blocks
5	Implementation/design decisions as Requirements	"REQ-005: The system shall use Redis for caching"	Move to SDS design document
6	Items without explicit source traceability	Any REQ missing a Trace line	Add **Trace:** Source: ... block

2.4 Statement Language Rules

Word	Usage	Rationale
shall	Required in all Requirement statements	Normative -- indicates mandatory behavior
should	Prohibited in Requirements	Ambiguous -- implies optional
will	Prohibited in Requirements	Ambiguous -- describes future intent, not mandate
can	Prohibited in Requirements	Ambiguous -- describes capability, not mandate
may	Acceptable in ACs and Refinements only	Indicates optionality within bounded scope

warning

Every Requirement statement must contain "shall". If you cannot write the statement with "shall", the item is likely not a Requirement.

2.5 Anti-Patterns Table

Anti-Pattern	Problem	Fix
Compound requirement: "The system shall validate AND save AND notify"	Multiple testable behaviors in one statement	Split into separate REQs or make secondary behaviors ACs
Vague language: "The system shall handle errors appropriately"	Not testable -- what counts as "appropriate"?	Specify each error condition and its response
Unbounded scope: "The system shall support all file formats"	Not verifiable	"The system shall support import of CSV and XLSX files"
Missing actor: "Data shall be validated"	Passive voice hides responsibility	"The system shall validate imported data"

---

3. Document Format -- Domain Files

Approved Section Order

Every SRS domain file follows this fixed section order (approved via QA pilot):

1. Metadata blockquote -- document identity (Version, Status, Scope, Domain)
2. Statement -- 1-2 paragraphs describing core behavior
3. Behavior Overview (Illustrative) -- Mermaid flowchart (rule files: Rule Flowchart)
4. Definitions -- term table (only if domain introduces specialized terms)
5. Domain-specific sections -- e.g., Status Categories, Resolution Code Mapping
6. Functional Requirements -- grouped by REQ-* with inline ACs
7. Configuration Options -- table with Affects column
8. Assumptions -- bullet list of runtime preconditions
9. UI Notes (Illustrative) -- presentation details grouped by FR number
10. Implementation (Illustrative) -- component mapping table
11. Traceability Matrix -- full matrix with Verification/Status columns
12. Notes -- informative bullets
13. Open Questions -- table with Owner/Date (omit if none)
14. Acceptance Tests -- Gherkin scenarios at end, with back-links to parent REQs
15. Appendix: Process Artifacts -- Completion Checklist + Reviewer Notes

Format Rules

• Blank line before every bullet list. A blank line is required after **Acceptance Criteria:** and after every *italic sub-header:*. Without it, bullets render as inline text in PDF output.
• Tests at end. All Gherkin acceptance tests belong under ## Acceptance Tests at the bottom of the file, not inline with their parent requirements. Each test links back to its parent REQ via [Up Back to requirement](#anchor).
• Group ACs by concern. Use italic sub-headers (*Matching Logic:*, *Error Handling:*) instead of flat AC-01/AC-02 lists.
• Use "Illustrative" not "Non-Normative". All diagrams, UI notes, and implementation sections are labeled "(Illustrative)".

Traceability mandate

Every Requirement must include a **Trace:** block linking to its source, SDS design section, and STD test cases (e.g., **Trace:** Source: REQ-ORIG-NNN | SDS: sds-file.md#anchor | STD: std-file.md#tv-nnn). Requirements without a Trace block violate the Phase 0 Semantic Lock Specification.

---

Domain files follow a consistent structure. Every section below is documented with its purpose and a copy-pasteable template snippet.

3.1 Metadata Blockquote

Appears immediately after the H1 title. Establishes document identity. The Status line distinguishes normative text (binding) from illustrative diagrams (explanatory only).

Template: Metadata Blockquote

3.2 Statement

A 1-2 paragraph overview explaining what this requirement area does and why it matters. Written in plain language for quick comprehension.

Template: Statement

3.3 Behavior Overview

A Mermaid diagram giving a high-level view of the domain's behavior. Always labeled "(Illustrative)".

Mermaid syntax pitfalls

• Pipe characters in labels conflict with edge syntax: use {"CT Diff > 2?"} not {|CT| > 2?}
• Forward slashes in labels need quotes: Node["/api/runs"] not Node[/api/runs]
• Node IDs must not match subgraph IDs
• Special characters (@, ()) in labels need quotes

Template: Behavior Overview

3.4 Definitions Table

Include only if the domain introduces specialized terms not defined elsewhere.

Template: Definitions Table

3.5 Functional Requirements

This is the core of the document. Each requirement gets a grouped heading and a Functional Requirement sub-heading. The {#req-domain-nnn} anchor is required for each REQ ID listed -- it enables deep linking.

Blank lines before bullets

A blank line is required before every bullet list. Without it, PDF rendering breaks. This applies to every AC block.

The Trace block must appear at the end of every FR section. It is mandatory and machine-detectable.

Templates: Functional Requirements

3.6 Configuration Options Table

Maps configuration keys to their defaults and affected requirements.

Template: Configuration Options Table

3.7 Assumptions

Lists prerequisite conditions assumed to hold at runtime.

Template: Assumptions

3.8 UI Notes (Illustrative)

Non-normative presentation details. Organized by FR number.

Template: UI Notes

3.9 Implementation Table

Maps requirements to code components. Labeled "(Illustrative)" because code locations may change.

Template: Implementation Table

3.10 Traceability Matrix

Traces each requirement to its verification method, implementation, and test cases.

Template: Traceability Matrix

3.11 Acceptance Tests

Located at the end of the document with back-links to their parent requirements.

Template: Acceptance Tests

3.12 Reviewer Notes

Documents consolidation decisions, ID changes, and conversion history. Critical for auditability.

Template: Reviewer Notes

---

4. Document Format -- Rule Files

Rule files share the domain file structure but add several rule-specific sections. The canonical example is srs/rules/rule-amb.md.

4.1 Metadata Blockquote (Extended)

Rule files add a Precedence field to the standard domain metadata.

Template: Rule Metadata Blockquote

4.2 Quick Reference Table

Immediately after the Statement section. Summarizes all REQs in the file.

Template: Quick Reference Table

4.3 Rule Summary Table

Summarizes the rule's key properties in a compact table.

Template: Rule Summary Table

4.4 Rule Flowchart (Illustrative)

Rule flowcharts use styled nodes to distinguish decision outcomes. Note the style declarations at the end.

Template: Rule Flowchart

4.5 Inputs/Outputs Tables

Added to individual FR sections for rules with complex data flow.

Template: Inputs/Outputs Tables

4.6 Resolution Code Mapping Table

For rules that process resolution codes.

Template: Resolution Code Mapping Table

4.7 Domain Code and File Naming

• Domain code pattern: REQ-RULES-{RULENAME}-NNN (e.g., REQ-RULES-AMB-001)
• File naming: rule-{name}.md (e.g., rule-amb.md, rule-westgards.md)
• Sidebar ID: srs/rules/rule-{name} (e.g., srs/rules/rule-amb)

4.8 Differences from Domain Files

Section	Domain Files	Rule Files
Metadata	4 fields	5 fields (adds Precedence)
Quick Reference	Not present	Required
Rule Summary	Not present	Required
Flowchart	Behavior Overview	Rule Flowchart (often more detailed)
Inputs/Outputs	Optional	Recommended for each FR
Resolution Mapping	Not applicable	Required if rule processes resolutions
Section heading	## Functional Requirements	## Requirements

---

5. Operations

5.1 Adding New Requirements

Step 1: Determine the Domain

Check which existing domain the requirement belongs to. The domain categories are:

Category	Domains
Run Management	upload-runs, fileimport, runfile-list, runfile-report, reports, reanalyze
Analysis & Rules	analytics, analyzer, errorcodes
User Interface	ui, tables, filters, globalui, keyboard, help, comments, notif, print, progress
Configuration	kitcfg, client-config, configio, site
User & Audit	user-management, user-settings, audit-log
Reference	nfr
Rule Definitions	61 individual rule files

If no existing domain fits, see Section 5.4: Creating New Domain Files.

Step 2: Find the Next ID

# Example for the KITCFG domain:
grep -o "REQ-KITCFG-[0-9]*" docusaurus/docs/srs/kitcfg.md | sort -t- -k3 -n | tail -1

# Example for a rule domain:
grep -o "REQ-RULES-AMB-[0-9]*" docusaurus/docs/srs/rules/rule-amb.md | sort -t- -k4 -n | tail -1

Step 3: ID Assignment Rules

• Format: REQ-{DOMAIN}-{NNN} (zero-padded to 3 digits)
• IDs are immutable once assigned -- never change, never reuse
• Sequential within domain: if last is REQ-KITCFG-015, next is REQ-KITCFG-016
• Parallel work: If multiple authors may be adding IDs concurrently, claim ID ranges in advance via a shared tracking issue to prevent collisions

Step 4: Write the Requirement

Follow the FR format from Section 3.5. At minimum, every new requirement needs:

1. A grouped heading with anchor: ### Title (REQ-DOMAIN-NNN) {#req-domain-nnn}
2. An FR sub-heading with "shall" statement: #### FR-DOMAIN-NNN Title
3. At least one Acceptance Criterion
4. A Trace block with source reference
5. A row in the Traceability Matrix
6. At least one Acceptance Test at the end of the file

Step 5: Update Supporting Sections

• Add a row to the Traceability Matrix
• Add Acceptance Tests at the end of the file
• Update the Implementation section if code already exists
• If the new REQ introduces terms, add them to the Definitions table

---

5.2 Modifying Existing Requirements

The ID Rule

The REQ ID is permanent. Never change it. Never reuse a retired ID. Everything else about a requirement can change -- its title, statement, ACs, priority, status -- but the ID is fixed for life.

What Can Change

Field	Changeable	Notes
REQ ID	Never	Immutable, non-reusable
Title	Yes	Refine for clarity
Statement	Yes	Update behavior description
Priority	Yes	Adjust if business priority shifts
Status	Yes	Draft, Review, Approved, Deprecated
Acceptance Criteria	Yes	Add, modify, remove ACs
Error Handling	Yes	Update conditions/responses
Traceability	Yes	Must update for new sources/tests

Document Changes in Reviewer Notes

Every modification must be recorded:

### Reviewer Notes

#### Version X.Y Changes

##### REQ-DOMAIN-NNN

**Change:** What was modified
**Reason:** Why it was modified
**Version:** X.Y
**Date:** YYYY-MM-DD

Previous Statement:
> The system shall [old behavior]...

New Statement:
> The system shall [new behavior]...

Cascade Updates

After modifying a requirement:

1. Update the Traceability Matrix if implementation references changed
2. Update Acceptance Tests if ACs were added, modified, or removed
3. Update the Implementation section if code was affected
4. Check cross-references in other SRS files (Related REQs in Trace blocks)

---

5.3 Deprecating Requirements

Step 1: Mark Status

Update the metadata or attribute table:

| Status | Deprecated (vX.Y) |

Step 2: Add Deprecation Notice

:::warning[Deprecation Notice]
This requirement is deprecated as of vX.Y.

- **Reason:** Why it was deprecated
- **Replacement:** REQ-DOMAIN-NNN or "None -- feature removed"
- **Migration:** Any steps needed for transition
:::

Step 3: Update Traceability

In the Traceability Matrix, set the Status column to Deprecated.

Step 4: Archive on Removal

When removing in a future version, move the entire requirement to an Archive section at the end of the file. Never delete requirement content -- it must remain accessible for historical traceability.

## Archive

### Removed in vX.Y

#### REQ-DOMAIN-NNN: Title (REMOVED)

**Removed:** vX.Y (YYYY-MM-DD)
**Reason:** Why removed

[Original requirement content preserved below]

---

5.4 Creating New Domain Files

File Location and Naming

• Path: docusaurus/docs/srs/{domain}.md
• Naming: lowercase with hyphens (e.g., audit-log.md, client-config.md)

Frontmatter

---
title: "Domain Name"
description: "One sentence describing what this domain covers"
sidebar_position: N
---

Position ranges by category:

Range	Category
1	Introduction
10-19	Run Management
20-29	Analysis & Rules
30-39	User Interface
40-49	Configuration
50-59	User & Audit
90-99	Reference

Sidebar Registration

Add the document ID to docusaurus/sidebars.js in the correct category. The ID is the file path relative to docs/ without the .md extension.

// In docusaurus/sidebars.js, add to the appropriate category:
{
  type: 'category',
  label: 'Configuration',
  items: [
    'srs/kitcfg',
    'srs/client-config',
    'srs/configio',
    'srs/site',
    'srs/new-domain',  // <-- new entry
  ],
},

Required Sections

Every new domain file must include all of these sections (in order):

1. H1 title + Metadata blockquote
2. Statement
3. Behavior Overview (Illustrative) -- Mermaid diagram
4. Definitions (if domain introduces terms)
5. Functional Requirements (at least one REQ)
6. Configuration Options
7. Assumptions
8. UI Notes (Illustrative)
9. Implementation (Illustrative)
10. Traceability Matrix
11. Acceptance Tests
12. Appendix: Process Artifacts (Completion Checklist + Reviewer Notes)

Validation

After creating the file:

cd docusaurus && npm run build 2>&1 | grep -c "couldn't be resolved"
# Result should be 0

---

5.5 Creating New Rule Files

File Location and Naming

• Path: docusaurus/docs/srs/rules/rule-{name}.md
• Naming: lowercase with hyphens, matching the rule's code identifier where possible
• Examples: rule-adj.md, rule-westgards.md, rule-combine-outcomes.md

Sidebar Registration

Rule files go in the "Rule Definitions" category in sidebars.js, ordered alphabetically by rule name:

{
  type: 'category',
  label: 'Rule Definitions',
  collapsed: true,
  items: [
    'srs/rules/rules',           // index page
    'srs/rules/rule-adj',
    'srs/rules/rule-adj-zika',
    'srs/rules/rule-amb',
    // ... alphabetical order ...
    'srs/rules/rule-new-rule',   // <-- insert alphabetically
    // ...
  ],
},

Domain Code

Rule files use the pattern REQ-RULES-{RULENAME}-NNN:

REQ-RULES-AMB-001
REQ-RULES-THRESHOLD-001
REQ-RULES-WESTGARDS-001

Required Sections (Beyond Domain Format)

In addition to the standard domain sections, rule files require:

1. Precedence field in metadata blockquote
2. Quick Reference table after Statement
3. Rule Summary table
4. Rule Flowchart (Illustrative) with styled nodes
5. Inputs/Outputs tables for each FR (recommended)
6. Resolution Code Mapping table (if applicable)

---

Quality Checklist

For the full SRS quality checklist, see the Authoring Checklists Reference.