SDS Update Guide

How to update Software Design Specification documents when features change.

Reference Documents

• Template & Standards: docusaurus/docs/sds/sds-01-introduction.md (frozen)
• Creation Plan: llm-instructions/archive/SDS_CREATION_PLAN.md (archived)
• Link Conventions: Link Conventions (merged into Contributor Guide)

---

SDS File Locations

All SDS files are in docusaurus/docs/sds/ (34 files total):

System-Level (6 files)

File	Content
sds-01-introduction.md	Template, standards, conventions (frozen)
sds-02-system-context.md	System boundaries, external actors
sds-03-architecture-overview.md	High-level architecture, patterns
sds-04-data-architecture.md	Entity model, schema design
sds-05-security-architecture.md	Auth, authorization, audit
sds-06-cross-cutting.md	Logging, errors, config patterns

Domain Design (14 files in domains/)

File	SRS Sources	Character
sds-domain-analytics.md	analytics, analyzer, progress	Stateful
sds-domain-audit.md	audit, errorcodes	Configuration-heavy
sds-domain-configio.md	configio	Integration
sds-domain-fileimport.md	fileimport, upload	Integration
sds-domain-globalui.md	globalui, ui, keyboard	Thin orchestration
sds-domain-kitcfg.md	kitcfg	Configuration-heavy
sds-domain-notif.md	notif	Thin orchestration
sds-domain-reanalyze.md	reanalyze, help	Algorithmic
sds-domain-reports.md	reports, print	Thin orchestration
sds-domain-runfile.md	runfile	Thin orchestration
sds-domain-runrpt.md	runrpt, comments	Stateful
sds-domain-settings.md	site, clientcfg, userset	Configuration-heavy
sds-domain-tables.md	tables, filters	Thin orchestration
sds-domain-usermgmt.md	usermgmt	Stateful

Rule Design (8 files in rules/)

File	Rule Count	Focus
sds-rules-engine.md	1	Framework, execution order
sds-rules-combine-outcomes.md	1	Outcome combination
sds-rules-outcome.md	15	Sigmoid, control status
sds-rules-classification.md	9	WDCLS, WDCT, thresholds
sds-rules-inhibition.md	8	IC handling
sds-rules-quantification.md	10	Quantity calculations
sds-rules-qc.md	6	Westgard, fluorescence
sds-rules-specialized.md	17	Well types, adjacency

Reference (4 files in reference/)

File	Content
sds-ref-api.md	API endpoint catalog
sds-ref-database.md	Table/column dictionary
sds-ref-config.md	Configuration option catalog
sds-ref-glossary.md	Term definitions

Traceability

File	Content
traceability/unified-traceability-matrix.md	REQ to Design/Test mapping (top-level, auto-generated)
sds-master-index.md	SDS master document index

---

When to Update Each Category

System-Level Documents

Change Type	Document to Update
Architecture patterns change	sds-03-architecture-overview.md
Data model changes	sds-04-data-architecture.md
Security/auth changes	sds-05-security-architecture.md
Cross-cutting concerns	sds-06-cross-cutting.md
External actors/boundaries	sds-02-system-context.md

Domain Documents

Update when the corresponding SRS domain changes:

Change Type	Action
New requirements added	Add to Requirements Covered table
Requirement logic changes	Update behavioral design section
New components	Update component architecture
Implementation mapping changes	Update Implementation Mapping section

Key: Domain docs mirror SRS ownership - one REQ belongs to one domain doc.

Rule Documents

Change Type	Action
Rule logic changes	Update truth tables and decision logic
New rules added	Add to appropriate rule group doc
Precedence changes	Update Rule Summary Block
New conditions	Add rows to truth tables

Reference Documents

Change Type	Document to Update
New API endpoints	sds-ref-api.md
Schema changes	sds-ref-database.md
Config options added/changed	sds-ref-config.md
New terms introduced	sds-ref-glossary.md

---

Key Conventions

Domain Character

Each domain document declares its character at the top:

Character	Description	Example Domains
Thin orchestration	Delegates to other domains	notif, runfile, tables
Configuration-heavy	Primarily config management	kitcfg, settings, audit
Stateful	Manages complex state	analytics, runrpt, usermgmt
Integration	External system integration	fileimport, configio
Algorithmic	Complex logic/calculations	reanalyze, rules

Section Obligations

Sections exist to be discharged, not necessarily filled. Use standard phrasings:

Obligation	Standard Phrasing
No state management	"This domain is stateless."
No complex algorithms	"All behavior is captured in the SRS acceptance criteria."
No external integrations	"This domain has no external dependencies."
No conditional logic	"No conditional sections apply."

Brevity rule: Short is correct when it accurately constrains behavior.

Rule Summary Block

Mandatory for all rule docs at 1.0:

## 1.0 Rule Summary Block

| Property | Value |
|----------|-------|
| Intent | What the rule determines |
| Inputs | Data consumed |
| Outputs | Results produced |

### Precedence

| Priority | Rule | When Applied |
|----------|------|--------------|
| 1 | RULE-A | Condition X |
| 2 | RULE-B | Condition Y |

Truth Tables

Mandatory for rules with 2+ conditions:

| Input1 | Input2 | Output | Notes |
|--------|--------|--------|-------|
| A | B | X | Precedence 1 |
| A | C | Y | Default |
| B | C | Z | Unreachable |

Include annotations:

• Precedence N - Order when multiple conditions match
• Default - Applied when no specific conditions match
• Unreachable - Logically impossible combinations

---

Cross-Reference Format

To SRS Documents

[SRS: analytics.md](../../srs/analytics.md)
[REQ-KITCFG-001](../../srs/kitcfg.md#req-kitcfg-001)

To Other SDS Documents

[SDS: Architecture](../sds-03-architecture-overview.md)
[See data model](../sds-04-data-architecture.md#entity-model)

To Reference Documents

See [Database Reference](../reference/sds-ref-database.md#table-name)
See [API Reference](../reference/sds-ref-api.md#endpoint)

From Code (code_tags.json)

Code-to-SDS traceability is maintained in tests/catalogue/code_tags.json. Each entry's sdd array references SDS anchors:

{
  "app/Http/Controllers/KitConfigController.php": {
    "srs": ["REQ-KITCFG-001"],
    "sdd": ["sds-domain-kitcfg.md#validation-logic"]
  }
}

---

Adding New Content

New Section in Domain Doc

1. Add section with anchor: ### Section Title {#anchor-name}
2. Document purpose, components, logic
3. Reference related SRS requirements
4. Update sds-master-index.md if major section

New Rule in Rule Doc

1. Add to appropriate rule group document
2. Include truth table if 2+ conditions
3. Add to Rule Summary Block precedence table
4. Update rule count in sds-rules-engine.md

New Reference Entry

1. Add entry in appropriate reference document
2. Follow existing format in that document
3. Update related domain docs if needed

---

Updating Diagrams

Mermaid Diagrams

Update inline in the document:

```mermaid
flowchart TD
    A[New Component] --> B[Existing Component]
    B --> C[Another Component]
```

Image-Based Diagrams

1. Update source diagram
2. Export as PNG
3. Replace file in docusaurus/static/media/
4. Verify rendering in docs

---

Quality Checklist

Before committing SDS changes:

• Domain character declared at document top
• Section obligations discharged (filled or explicitly marked N/A)
• Requirements Covered table complete and current
• Implementation Mapping section current
• Cross-references verified (run Docusaurus build)
• Frontmatter current (title, description, sidebar_position)
• Rule docs have Rule Summary Block
• Truth tables present for rules with 2+ conditions

---

Validation

Link Verification

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

Coverage Check

Verify all requirements are traced:

# Count REQs in SRS
grep -roh "REQ-[A-Z]*-[0-9]*" docusaurus/docs/srs/*.md docusaurus/docs/srs/rules/*.md | sort -u | wc -l

# Count REQs in SDS Requirements Covered tables
grep -roh "REQ-[A-Z]*-[0-9]*" docusaurus/docs/sds/domains/*.md | sort -u | wc -l

---

Common Patterns

Adding a New Domain Feature

1. Update SRS with new requirements
2. Update corresponding sds-domain-*.md:
   • Add to Requirements Covered table
   • Update behavioral design section
   • Update Implementation Mapping
3. Update reference docs if needed (API, config, database)
4. Verify cross-references

Modifying Rule Logic

1. Update rule SRS file
2. Update corresponding sds-rules-*.md:
   • Update truth table
   • Update precedence if changed
   • Update Rule Summary Block
3. Verify dependent domain docs aren't affected

Deprecating a Feature

1. Add deprecation notice in SRS
2. Add deprecation notice in SDS domain doc
3. Keep section content for reference
4. Document removal timeline