SRS Update Guide

How to add, modify, and deprecate requirements in SRS documentation.

Reference Documents

• Format Reference: docusaurus/docs/guides/guide-srs-authoring.md (canonical authoring guide; old template archived to llm-instructions/archive/srs_template_v1.md)
• Conversion Workflow: llm-instructions/archive/AGENT_requirements_to_srs.md (archived)

SRS File Locations

Content	Location
Domain SRS files	docusaurus/docs/srs/*.md (29 files)
Rule definitions	docusaurus/docs/srs/rules/*.md (61 files)
Introduction	docusaurus/docs/srs/introduction.md

Important: All SRS files are now in Docusaurus. Do NOT edit files in output/srs/ - they are archived. See Link Conventions for link formatting and path conventions.

---

Adding New Requirements

Step 1: Determine Domain

Check if the new requirement fits an existing domain or needs a new one.

Existing Domains:

ls docusaurus/docs/srs/*.md | xargs -I {} basename {} .md

Domain Taxonomy:

• 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

Step 2: Assign Requirement ID

Format: REQ-{DOMAIN}-{NNN}

Find next ID:

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

Rules:

• IDs are immutable - once assigned, never change
• Sequential within domain, zero-padded to 3 digits
• Example: If last is REQ-KITCFG-015, next is REQ-KITCFG-016

Step 3: Write Requirement

Use the format from the SRS authoring guide:

#### REQ-{DOMAIN}-{NNN}: {Short Title}

| Attribute | Value |
|-----------|-------|
| ID | REQ-{DOMAIN}-{NNN} |
| Priority | HIGH / MEDIUM / LOW |
| Status | Draft |
| Verification | Test / Inspection / Analysis |

**Statement**

The system shall {verb} {object} {conditions}.

**Acceptance Criteria**

| ID | Criterion |
|----|-----------|
| AC-01 | The system shall {testable condition} |
| AC-02 | The system shall {testable condition} |

**Error Handling**

| Condition | Response |
|-----------|----------|
| {Error condition} | The system shall {response} |

**Traceability**

| Type | Reference |
|------|-----------|
| Source | {PRD section, Change ID, etc.} |
| Jira | {BT-XXX if applicable} |
| Tests | [Pending] |
| Related | {REQ-OTHER-NNN if dependencies} |

Step 4: Place in Document

1. Find the appropriate functional group heading
2. Add requirement in logical order (usually end of group)
3. If new functional group needed, add ### {Group Name} heading

Step 5: Update Traceability Matrix

Add row to the Traceability Matrix section:

| REQ-{DOMAIN}-{NNN} | {Title} | {Implementation} | {Test Cases} | Draft |

Step 6: Add Implementation Section (if code exists)

If the code implementing this requirement already exists:

### Implementation

| Component | Location |
|-----------|----------|
| Controller | `{Controller}@{method}` |
| Service | `{Service}@{method}` |
| Model | `{Model}` |

---

Modifying Existing Requirements

Key Rule: Preserve ID

NEVER change the REQ ID. The ID is a permanent identifier for traceability.

What Can Be Modified

Section	Guidance
Title	Can refine for clarity
Statement	Can update behavior description
Priority	Can change if business priority shifts
Status	Update as appropriate (Draft → Review → Approved)
Acceptance Criteria	Can add, modify, remove ACs
Error Handling	Can update error conditions/responses
Traceability	Must update for new sources/tests

Document Changes

Add a note in the Reviewer Notes section:

## Reviewer Notes

### Version {X.Y} Changes

#### REQ-{DOMAIN}-{NNN}

**Change:** {What changed}
**Reason:** {Why it changed}
**Version:** {X.Y}
**Date:** {YYYY-MM-DD}

Previous Statement:
> The system shall {old behavior}...

New Statement:
> The system shall {new behavior}...

Update Related Sections

1. Update Traceability Matrix if implementation changed
2. Update Acceptance Tests if ACs changed
3. Update Implementation section if code changed

---

Deprecating Requirements

Step 1: Mark as Deprecated

Update the Status in the attribute table:

| Status | Deprecated (v{X.Y}) |

Step 2: Add Deprecation Note

Add to the requirement's Notes or create a Deprecation section:

**Deprecation Notice**

This requirement is deprecated as of v{X.Y} and will be removed in v{Z.W}.
- **Reason:** {Why deprecated}
- **Replacement:** {REQ-DOMAIN-NNN or "None - feature removed"}
- **Migration:** {Any migration steps needed}

Step 3: Update Traceability

In Traceability Matrix, update Status column:

| REQ-{DOMAIN}-{NNN} | {Title} | {Implementation} | {Tests} | Deprecated |

Step 4: Archive (on removal)

When actually removing in a future version:

1. Move the entire requirement to an ## Archive section at end of document
2. Add removal note with version and date
3. Keep for historical traceability (do NOT delete)

## Archive

### Removed in v{X.Y}

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

**Removed:** v{X.Y} ({YYYY-MM-DD})
**Reason:** {Why removed}

[Original requirement content preserved for traceability]

---

Creating New Domain Files

When a new capability doesn't fit existing domains:

Step 1: Create File

Use the SRS authoring guide for the full template structure.

File: docusaurus/docs/srs/{newdomain}.md

Step 2: Add Frontmatter

---
title: "{Domain Name}"
description: "{One sentence description for SEO}"
sidebar_position: {N}
---

Position Ranges:

• 10-19: Run Management
• 20-29: Analysis & Rules
• 30-39: User Interface
• 40-49: Configuration
• 50-59: User & Audit
• 90-99: Reference

Step 3: Fill Sections

1. Overview - What capability space this domain covers
2. Definitions - Domain-specific terms
3. Assumptions - Preconditions for all requirements
4. Requirements - Grouped by functional area
5. Configuration Options - Configurable parameters
6. UI Detail (Non-normative) - Presentation details
7. Notes - Historical context, implementation notes
8. Reviewer Notes - Consolidation decisions
9. Traceability Matrix - REQ → Implementation → Tests
10. Acceptance Tests - Gherkin-style tests
11. Completion Checklist - Quality gates

Step 4: Update Index

Add to docusaurus/docs/srs/introduction.md document index.

---

Rule File Updates

Rule definitions are in docusaurus/docs/srs/rules/ (61 files). These follow a different pattern than domain SRS files.

Rule File Structure

Each rule file (e.g., rule-adj.md, rule-westgard.md) documents a specific analysis rule:

• Rule name and acronym
• When it applies
• Logic/algorithm
• Inputs and outputs
• Error conditions

When to Update Rule Files

Change Type	Action
New rule added to system	Create new rule-{name}.md file
Rule logic changed	Update existing rule file
Rule deprecated	Add deprecation notice, keep file
Rule parameters changed	Update configuration section

Rule File Naming

• Lowercase with hyphens: rule-{rule-name}.md
• Match the rule's code identifier where possible
• Example: rule-adj.md for Adjacent Well Check, rule-westgard.md for Westgard Rules

Cross-References

• Rules reference SRS requirements via REQ-RULES-NNN or related domain REQs
• SDS rule docs (e.g., sds-rules-outcome.md) contain design details
• Domain SRS files (e.g., analytics.md) reference rules they use

See Link Conventions for link formatting conventions.

---

Quality Checklist

Before committing SRS changes:

• REQ IDs follow format REQ-{DOMAIN}-{NNN}
• No duplicate IDs within domain
• All new requirements have Statement + ACs + Traceability
• Modified requirements have Reviewer Notes documenting change
• Deprecated requirements have deprecation notice
• Traceability Matrix updated
• Frontmatter sidebar_position correct
• Acceptance Tests added/updated for new ACs

---

Common Mistakes to Avoid

Mistake	Why It's Wrong	Fix
Changing REQ ID	Breaks traceability	Keep original ID, update content
Deleting deprecated REQs	Loses history	Archive instead
Missing ACs	Requirement not testable	Add at least one AC
UI mechanics in Statement	Not UI-stable	Move to UI Detail section
Compound requirements	Hard to trace/test	Split into separate REQs
No source traceability	Can't verify origin	Add Source to Traceability