Skip to main content
Version: 3.0.1

Authoring Checklists Reference

Single source of truth for documentation quality checklists and validation commands. Individual guides link here rather than duplicating.

Pre-Commit Checklist​

Run through this checklist before every commit that touches documentation files.

  • npm run build produces 0 broken link warnings
  • bash docusaurus/scripts/validate-mermaid.sh docusaurus/docs produces 0 errors
  • python docusaurus/scripts/add-req-anchors.py --dry-run shows no missing anchors
  • No files modified in versioned_docs/ (unless intentionally replacing a snapshot)
  • No files modified in sdd/ (deprecated)
  • sidebar_position does not conflict with existing files in the same category
  • All new files tracked in sidebars.js
  • code_tags.json updated if code changed (add/move/remove file mappings)
  • Cross-document references are bidirectional (docs link to code AND code links to docs)

See also: SRS Quality Checklist for SRS-specific items, SDS Quality Checklist for SDS-specific items.

New Requirement Checklist​

Use when adding a new REQ-* to an existing or new SRS file.

  • Item classified per taxonomy: REQUIREMENT, ACCEPTANCE_CRITERIA, REFINEMENT, UI_DETAIL, or CONFIG_OPTION (see SRS Guide: Classification)
  • Assigned next sequential REQ ID (REQ-{DOMAIN}-{NNN}, zero-padded to 3 digits)
  • Requirement statement uses "shall" language
  • At least one Acceptance Criterion present
  • Trace block with source reference included
  • Traceability Matrix row added
  • Implementation section populated (if code exists)
  • Acceptance Test added at end of file with back-link
  • Sidebar entry present in sidebars.js
  • npm run build passes with 0 broken links
  • Reviewer Notes updated with version and rationale

Modify Requirement Checklist​

Use when changing an existing requirement's statement, ACs, or behavior.

  • REQ ID unchanged (IDs are immutable)
  • Change documented in Reviewer Notes section
  • Acceptance Criteria updated if behavior changed
  • Traceability Matrix updated if implementation references changed
  • Acceptance Tests updated for new or changed ACs
  • Implementation section updated if code was affected
  • npm run build passes with 0 broken links

New File Checklist​

Use when creating a new documentation file of any type.

  • File placed in correct directory (srs/, srs/rules/, sds/domains/, sds/rules/, etc.)
  • Frontmatter includes all required fields (title, description, sidebar_position)
  • sidebar_position falls within the correct range for the category
  • Document ID added to sidebars.js in the correct category
  • All required sections present (see SRS Authoring Guide or SDS Authoring Guide)
  • Internal links use correct relative paths for the file's directory depth
  • Mermaid diagrams validate without errors
  • npm run build passes with 0 broken links

New SDS Content Checklist​

Use when adding a new SDS domain document, rule document, or major new section.

  • Domain character declared in metadata blockquote
  • Requirements Covered table references all applicable SRS REQs
  • Mandatory sections present: 1 (Overview), 2 (Component Architecture), 8 (Implementation Mapping), 9 (Design Decisions), 11 (Related Documents)
  • Conditional sections discharged with standard phrasings if unused (see SDS Guide: Brevity Rule)
  • Implementation Mapping (section 8) populated with code paths
  • sds-master-index.md updated for new sections or documents
  • Cross-references use correct relative paths
  • npm run build passes with 0 broken links

SRS Quality Checklist​

Use before committing any SRS change. Covers SRS-specific format and content rules beyond the general Pre-Commit Checklist.

Identifiers and Statements​

  • REQ IDs follow format REQ-{DOMAIN}-{NNN} (zero-padded 3 digits)
  • No duplicate IDs within the domain
  • Every Requirement statement contains "shall"

Content Completeness​

  • All new requirements have Statement + ACs + Trace + Error Handling
  • Modified requirements have Reviewer Notes documenting the change
  • Deprecated requirements have deprecation notice
  • Traceability Matrix updated
  • Acceptance Tests added/updated for new or changed ACs

Formatting​

  • Blank line before every bullet list
  • Mermaid diagrams render without errors
  • All diagrams labeled "(Illustrative)"
  • No use of "non-normative" (use "Illustrative" instead)

Build​

  • npm run build produces 0 broken link warnings for the changed file
  • Frontmatter sidebar_position is correct for the category range

Process Artifacts (Completion Checklist)​

The following items appear in the Appendix of each SRS file as a completed ([x]) checklist. Verify all are satisfied before finalizing a file:

  • All requirements are capability-level (describe behavior, not UI)
  • Requirement variants consolidated (no requirement explosion)
  • UI details are fully demoted to Illustrative section
  • Configuration options are not encoded as requirements
  • Acceptance criteria describe behavior, not UI mechanics
  • Every requirement has acceptance criteria and source traceability
  • Error handling addressed for I/O, validation, and external system requirements
  • Open questions documented with owners assigned
  • Consolidations documented in Reviewer Notes with reversibility info
  • Module can survive a full UI redesign unchanged
  • Refinements do not introduce new capabilities
  • Traceability matrix is complete
  • Mermaid diagram present and renders without errors
  • Diagram marked as (Illustrative)
  • No "non-normative" text anywhere
  • All original REQ-* IDs preserved
  • All ACs preserved with blank lines before bullet lists
  • Tests at end with back-links

SDS Quality Checklist​

Use before committing any SDS change. Covers SDS-specific format and content rules beyond the general Pre-Commit Checklist.

Structure and Metadata​

  • Domain character declared in metadata blockquote
  • All mandatory sections present (1, 2, 8, 9, 11)
  • Conditional sections either have substantive content or are discharged with standard phrasings
  • Frontmatter is current (title, description, sidebar_position)

Requirements Traceability​

  • Requirements Covered table includes all REQ-* from the corresponding SRS
  • Implementation Mapping section is current (code paths exist)
  • Cross-references are valid relative paths

Rule Documents (additional items)​

  • Rule docs include section 1.0 Rule Summary Block
  • Truth tables present for rules with 2+ conditions, with Precedence/Default/Unreachable annotations
  • sds-master-index.md updated if new sections or documents were added
  • Mermaid diagrams validate: bash docusaurus/scripts/validate-mermaid.sh docusaurus/docs
  • Docusaurus build passes: cd docusaurus && npm run build 2>&1 | grep -c "couldn't be resolved" (should be 0)

Validation Commands​

All commands are run from the repository root unless otherwise noted.

Build Check (Authoritative)​

The Docusaurus build is the primary quality gate. It catches broken links, malformed frontmatter, and missing sidebar entries.

cd docusaurus && npm run build 2>&1 | tail -5

A successful build produces 0 lines containing "couldn't be resolved". To count broken links specifically:

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

Mermaid Diagram Validation​

Validates all Mermaid diagrams using the exact mermaid version bundled with Docusaurus (zero version drift).

bash docusaurus/scripts/validate-mermaid.sh docusaurus/docs

Or directly:

node docusaurus/scripts/validate-mermaid.mjs docusaurus/docs

REQ Anchor Check​

Adds explicit {#req-domain-nnn} anchors to REQ headers. Idempotent -- safe to run multiple times.

# Preview (dry run)
python docusaurus/scripts/add-req-anchors.py --dry-run

# Apply
python docusaurus/scripts/add-req-anchors.py

Jira Reference Linking​

Converts bare Jira references (BT-, CST-, PCRAI-*) to Atlassian links.

# Preview (dry run)
./docusaurus/scripts/link-jira-refs.sh -n

# Apply
./docusaurus/scripts/link-jira-refs.sh

Fixes relative link paths across documentation files.

warning

This script is NOT idempotent. Running it multiple times corrupts paths. Always git restore the docs directory before running:

git restore docusaurus/docs/
python docusaurus/scripts/fix-docusaurus-links.py --docs-root docusaurus/docs --dry-run   # Preview
python docusaurus/scripts/fix-docusaurus-links.py --docs-root docusaurus/docs --apply     # Apply

Code Mapping Orphan Check​

Finds REQ IDs in code_tags.json that are not defined in any SRS file.

jq -r '.by_srs | keys[]' tests/catalogue/code_tags.json | sort -u > /tmp/code-refs.txt
grep -roh "REQ-[A-Z]*-[0-9]*" docusaurus/docs/srs/*.md docusaurus/docs/srs/rules/ | sort -u > /tmp/srs-ids.txt
comm -23 /tmp/code-refs.txt /tmp/srs-ids.txt
# Should return empty (no orphaned references)

Local Development Server​

For previewing changes with hot reload during authoring:

cd docusaurus && npm start

Validation Command Summary​

TaskCommand
Full build (authoritative)cd docusaurus && npm run build
Mermaid validationbash docusaurus/scripts/validate-mermaid.sh docusaurus/docs
Add REQ anchorspython docusaurus/scripts/add-req-anchors.py
Preview REQ anchorspython docusaurus/scripts/add-req-anchors.py --dry-run
Convert Jira refs./docusaurus/scripts/link-jira-refs.sh
Preview Jira refs./docusaurus/scripts/link-jira-refs.sh -n
Preview link fixespython docusaurus/scripts/fix-docusaurus-links.py --docs-root docusaurus/docs --dry-run
Code mapping orphan checkSee full command above
Dev server (hot reload)cd docusaurus && npm start