ma-agents 2.17.0 → 2.18.0

package/lib/bmad-workflows/mil498/ssdd/instructions.md

@@ -6,6 +6,8 @@
 
 Generate a compliant SSDD document by extracting and organizing system architectural design decisions from existing project artifacts into the MIL-STD-498 SSDD template structure. The SSDD describes the system-level design — how the system is organized into components (HWCIs, CSCIs, and manual operations) and how they interact.
 
+**Critical principle**: The SSDD describes design decisions from the user's point of view, ignoring internal implementation details. Design decisions must be framed as responses to specific requirements — not as technology selections.
+
 ## Step 1 — Discover Project Artifacts
 
 Search the project for the following artifacts. Communicate in {communication_language}. Inform {user_name} which artifacts were found and which are missing.
@@ -22,6 +24,19 @@ Search the project for the following artifacts. Communicate in {communication_la
 
 If **required** artifacts are missing, warn the user and ask whether to proceed with available data or stop.
 
+### Document Dependencies
+
+The SSDD is best generated after the following MIL-STD-498 predecessor documents:
+
+| Predecessor | Relationship | Search Pattern |
+|-------------|-------------|----------------|
+| SSS (System/Subsystem Specification) | Recommended — provides the system requirements the SSDD designs against | `**/SSS.md` |
+| OCD (Operational Concept Description) | Optional — provides operational context | `**/OCD.md` |
+
+If predecessor documents exist, they MUST be loaded and used as primary inputs. The SSDD should reference them in Section 2 and trace design decisions to their requirements.
+
+If recommended predecessors have NOT been generated yet, **alert {user_name}**: "The SSS has not been generated yet. The SSDD is typically produced after the SSS, since it designs against system requirements defined there. Would you like to proceed without it, or generate the SSS first?"
+
 ## Step 2 — Load Template
 
 Read the SSDD template from:
@@ -29,9 +44,49 @@ Read the SSDD template from:
 
 This defines the required DID sections and content expectations for each paragraph.
 
+## Step 2.5 — CSCI Discovery Interview
+
+Before generating the document, you must establish the correct CSCI decomposition through an interactive interview with {user_name}. **Do NOT map repositories, microservices, or deployment units 1:1 to CSCIs.** A CSCI is a configuration item — a logically cohesive unit that is independently specified, designed, tested, and managed.
+
+### Phase A: Initial Analysis
+
+Analyze the Architecture document and identify:
+- All services, modules, repositories, and deployment units mentioned
+- Functional domains they belong to (e.g., detection, alerting, user management, frontend)
+- Shared release cycles, shared teams, shared test suites
+- Data coupling between components (which services share databases or communicate frequently?)
+
+### Phase B: Propose CSCI Hypothesis
+
+Present {user_name} with a proposed CSCI decomposition that groups related services/modules into logically cohesive CSCIs. For each proposed CSCI:
+- Give it a descriptive name and project-unique identifier
+- List the services/modules/components it contains (these become CSCs — Computer Software Components — within the CSCI)
+- State the functional rationale for the grouping
+- Identify the system requirements allocated to it
+
+### Phase C: Guided Questions
+
+Ask {user_name} the following questions to validate and refine the decomposition:
+
+1. **Release boundaries**: "Which of these services/modules share a release cycle and are always deployed together?"
+2. **Team boundaries**: "Which components are developed and maintained by the same team?"
+3. **Test boundaries**: "Which components are always tested together as a unit?"
+4. **Delivery boundaries**: "What are your contractual or organizational delivery boundaries — what does the customer/stakeholder receive as distinct deliverables?"
+5. **Configuration management**: "Which components are independently baselined and version-controlled as a unit?"
+
+### Phase D: Refine and Confirm
+
+Based on {user_name}'s answers:
+- Merge or split CSCIs as needed
+- Ensure each CSCI has clear functional cohesion
+- Assign final project-unique identifiers (e.g., CSCI-SA for Situational Awareness, CSCI-FE for Frontend)
+- Get explicit approval from {user_name} before proceeding to document generation
+
+**Do NOT proceed to Step 3 until {user_name} approves the CSCI decomposition.**
+
 ## Step 3 — Generate Document
 
-Write the document in {document_output_language}, populating each template section:
+Write the document in {document_output_language}, populating each template section.
 
 ### Section 1: Scope
 - **1.1 Identification**: Extract system name, version, and project-unique identifiers from PRD/Product Brief
@@ -39,60 +94,88 @@ Write the document in {document_output_language}, populating each template secti
 - **1.3 Document overview**: Describe this SSDD document's purpose, contents, and any security/privacy considerations
 
 ### Section 2: Referenced documents
-- List all project artifacts, standards, and external references used as inputs
+- List all project artifacts, standards, and external references used as inputs. Include number, title, revision, and date for each
 
 ### Section 3: System-wide design decisions
 
-Document design decisions that apply across the entire system. For each decision, reference the requirement(s) it satisfies:
+**CRITICAL BEHAVIORAL GUIDANCE**: This section describes the system's behavioral design — how it will behave from a user's point of view in meeting its requirements, ignoring internal implementation. Follow these rules strictly:
 
-- **a. Input/output design**: System inputs, outputs, and user/external interfaces. Describe what the system accepts and produces from the Architecture document
-- **b. Behavioral design**: System behavior in response to inputs and conditions — actions, response times, performance characteristics, algorithms, handling of invalid inputs. Extract from PRD and Architecture
-- **c. Database/data design**: How databases and data files appear to users. Data models and storage approaches from Architecture
-- **d. Safety, security, privacy**: Selected approaches to meeting these requirements from PRD
-- **e. Hardware design choices**: Physical characteristics if applicable (for hardware-software systems)
-- **f. Other system-wide decisions**: Flexibility, availability, maintainability approaches. Technology stack selections and their rationale from Architecture
+1. **Requirements-driven**: Every design decision MUST cite the specific requirement(s) it satisfies (e.g., "To satisfy NFR-P2 (< 1s detection latency)...")
+2. **Behavioral, not implementation**: Describe patterns and approaches, NOT specific tools or products. Write "An asynchronous message distribution pattern is selected..." NOT "RabbitMQ serves as the message broker..."
+3. **Technology names belong in the Architecture document**, not here. If a technology choice is essential context, mention it parenthetically after the behavioral description
+4. **State-dependent decisions**: If a design decision depends on system states or modes, indicate this dependency explicitly
+
+For each of the following subsections, document the design decisions and reference their driving requirements:
+
+- **a. Input/output design**: What the system accepts and produces. Describe system inputs, outputs, and user/external interfaces from the user's perspective. If Interface Design Descriptions (IDDs) exist, they may be referenced
+- **b. Behavioral design**: How the system behaves in response to inputs and conditions — actions, response times, performance characteristics, selected algorithms/rules, and handling of invalid inputs or error conditions. Describe behavioral patterns (event-driven processing, request-response cycles, etc.) without naming specific tools
+- **c. Database/data design**: How databases and data files appear to users and external systems. Describe data models, storage approaches, and data lifecycle from the user's perspective. If Database Design Descriptions (DBDDs) exist, they may be referenced
+- **d. Safety, security, privacy**: Selected approaches to meeting safety, security, and privacy requirements. Place these in **separate subparagraphs** as the DID requires special treatment for critical requirements
+- **e. Hardware/physical design choices**: Physical characteristics if applicable (for hardware-software systems) — size, color, shape, weight, materials, markings
+- **f. Other system-wide decisions**: Flexibility, availability, maintainability approaches. Describe the rationale for architectural patterns selected (e.g., "A service-isolation pattern is selected to satisfy NFR-A1 availability requirement, enabling independent failure recovery")
 
 ### Section 4: System architectural design
 
-- **4.1 System components**:
-  - Identify all system components (CSCIs, HWCIs, manual operations) from the Architecture document
-  - Assign project-unique identifiers to each component
-  - Show static relationships using component/block diagrams
-  - State each component's purpose and the system requirements allocated to it
-  - Identify each component's development status (new, reuse, reengineer)
-  - For computer systems: describe hardware resources (processors, memory, I/O, storage, networking) with specifications
+- **4.1 System components** (items a through f — all are required):
+
+  **a.** Identify all system components using the approved CSCI decomposition from Step 2.5. Each CSCI shall have a project-unique identifier. For each CSCI, list the CSCs (services, modules) it contains. Also identify HWCIs and manual operations as applicable. Note: a database may be treated as a CSCI or as part of a CSCI.
+
+  **b.** Show the static ("consists of") relationships using component/block diagrams. Multiple relationship views may be presented (structural, deployment, data ownership).
+
+  **c.** State each component's purpose and the system requirements allocated to it. (Alternatively, allocation may be provided in Section 5.a.)
+
+  **d.** Identify each component's development status: new development, existing reuse as-is, existing design reuse, reengineering, planned for a specific build, etc. For existing components, provide identifying information (name, version, documentation references, location).
+
+  **e.** For each computer system or hardware aggregate, describe computer hardware resources: processors, memory, I/O devices, auxiliary storage, communications/network equipment. Include:
+    - Manufacturer, model, speed/capacity for processors
+    - Type, size, speed, configuration for memory
+    - Type, speed/capacity for I/O devices
+    - Type, amount, speed for auxiliary storage
+    - Data transfer rates, topologies, protocols for network equipment
+    - Growth capabilities and diagnostic capabilities
+    - Resource utilization allocation per CSCI (e.g., "20% of resource capacity allocated to CSCI-SA")
+
+  **f.** Present a **specification tree** — a diagram that identifies and shows the relationships among the planned specifications for the system components. This is a tree showing which specification documents (SSS, SRS, SDD, IRS, etc.) apply to which components.
 
 - **4.2 Concept of execution**:
-  - Describe dynamic relationships between components from Architecture
-  - Include: execution flow, data flow, state transitions, timing/sequencing, priorities, interrupt handling, concurrency, dynamic allocation
-  - Use sequence diagrams or flow diagrams where helpful
+  - Describe dynamic relationships between components — how they interact during system operation
+  - Include: execution flow, data flow, dynamically controlled sequencing, state transitions, timing/sequencing, priorities, interrupt handling, concurrent execution, dynamic allocation/deallocation, exception handling
+  - Use sequence diagrams, timing diagrams, or state transition diagrams where helpful
 
 - **4.3 Interface design**:
-  - **4.3.1 Interface identification and diagrams**: List all interfaces with unique identifiers, identify fixed vs. developing interfaces, provide interface diagrams
-  - **4.3.x (per interface)**: For each interface, document:
-    - Interfacing entities and their characteristics
-    - Data elements: names, types, sizes, formats, units, ranges, accuracy, constraints
-    - Data assemblies: records, messages, files, displays with structure and relationships
-    - Communication methods: links, message formats, flow control, data rates, routing
-    - Protocols: layers, packeting, error control, synchronization
-    - Physical compatibility considerations
+  - **4.3.1 Interface identification and diagrams**: List all interfaces with project-unique identifiers. Identify interfacing entities by name, number, version. State which entities have fixed interface characteristics vs. developing ones. Provide interface diagrams.
+  - **4.3.x (per interface)**: For each interface, document the following as applicable:
+    - **a.** Priority assigned to the interface
+    - **b.** Type of interface (real-time data transfer, storage-and-retrieval, etc.)
+    - **c.** Data elements: names/identifiers (project-unique, natural-language, technical), data types, sizes/formats, units, ranges, accuracy/precision, timing/frequency/volume constraints, security/privacy constraints, sources and recipients
+    - **d.** Data element assemblies: records, messages, files, displays — their names, structure, medium, visual/auditory characteristics, relationships, constraints, sources and recipients
+    - **e.** Communication methods: links/media, message formatting, flow control, data transfer rates, routing/addressing, transmission services, safety/security considerations
+    - **f.** Protocols: priority/layer, packeting/fragmentation, error control/recovery, synchronization, status/reporting
+    - **g.** Physical compatibility considerations (dimensions, tolerances, loads, voltages, plug compatibility)
 
 ### Section 5: Requirements traceability
 - **5.a**: Map each system component to the system requirements it satisfies
 - **5.b**: Map each system requirement to the components that address it
+- Ensure every system requirement is accounted for in both directions
 
 ### Section 6: Notes
-- Glossary of terms, acronyms, and abbreviations
+- Alphabetical listing of all acronyms, abbreviations, and their meanings
+- Glossary of terms and definitions needed to understand this document
 - Background information to aid understanding
 
+### Appendix A
+- Include any supplementary material (charts, detailed data, classified information) that supports the main body
+- Reference each appendix from the main body where the data would normally appear
+
 ## Step 4 — Validate
 
 Before presenting to the user, verify:
-- All template sections are populated or marked "Not applicable" with justification
-- Every component has a unique identifier
-- System-wide design decisions reference their driving requirements
-- Interface descriptions are complete and consistent from both sides
-- Requirements traceability covers all system requirements
+- All template sections (1-6 and Appendix A) are populated or marked "Not applicable" with justification
+- Every CSCI has a project-unique identifier and represents a logically cohesive grouping (not a 1:1 service mapping)
+- The specification tree (4.1.f) is present and shows relationships among planned specifications
+- System-wide design decisions (Section 3) are framed as behavioral responses to requirements — **no tool/product names appear as primary descriptions**
+- Interface descriptions (4.3.x) cover all seven aspects (a through g) where applicable
+- Requirements traceability (Section 5) covers all system requirements in both directions
 - Document is written in {document_output_language}
 
 ## Step 5 — Review
@@ -100,9 +183,11 @@ Before presenting to the user, verify:
 Present the complete document to {user_name} for review.
 Highlight any sections where information was inferred or assumptions were made.
 Specifically ask about:
-- Are all system components identified?
-- Are the interface descriptions accurate?
+- Is the CSCI decomposition correct? Are there components that should be merged or split?
+- Are the interface descriptions accurate and complete?
 - Are there additional design decisions not captured in the Architecture?
+- Does Section 3 correctly describe behavioral design without leaking implementation details?
+- Is the specification tree in 4.1.f accurate?
 
 Offer to refine any section based on feedback.
 
@@ -112,7 +197,9 @@ Write the final document to:
 `{output_folder}/planning-artifacts/SSDD.md`
 
 Confirm the file was saved and display a summary of:
-- Number of system components identified
+- Number of CSCIs identified (with their identifiers)
+- Number of CSCs per CSCI
 - Number of interfaces documented
 - Number of system-wide design decisions captured
+- Specification tree completeness
 - Any sections marked "Not applicable"

package/lib/bmad-workflows/mil498/sss/instructions.md

@@ -20,6 +20,20 @@ Search the project for the following artifacts. Communicate in {communication_la
 
 If **required** artifacts are missing, warn the user and ask whether to proceed with available data or stop.
 
+### Document Dependencies
+
+The SSS is typically one of the earliest MIL-STD-498 documents generated, after the OCD. It defines system-level requirements that downstream documents (SSDD, SRS) will design against and trace to.
+
+| Predecessor | Relationship | Search Pattern |
+|-------------|-------------|----------------|
+| OCD (Operational Concept Description) | Recommended — provides operational context and user needs | `**/OCD.md` |
+
+If the OCD has been generated, it MUST be loaded and used as an input — particularly for deriving capability requirements (3.2) and understanding operational scenarios.
+
+If the OCD has NOT been generated yet, **inform {user_name}**: "The OCD has not been generated yet. The SSS benefits from the operational context in the OCD. Would you like to proceed without it, or generate the OCD first?"
+
+**Note**: The SSS feeds into the SSDD, SRS, and STD. Ensure requirements are written to be traceable — each requirement needs a unique identifier that downstream documents can reference.
+
 ## Step 2 — Load Template
 
 Read the SSS template from:
@@ -29,59 +43,122 @@ This defines the required DID sections and content expectations for each paragra
 
 ## Step 3 — Generate Document
 
-Write the document in {document_output_language}, populating each template section. Keep requirements at the **system/subsystem level** — avoid low-level software implementation details.
+Write the document in {document_output_language}, populating each template section. Keep requirements at the **system/subsystem level** — avoid low-level software implementation details. Each requirement shall be assigned a project-unique identifier, be stated so that an objective test can be defined for it, and be annotated with qualification method(s).
 
 ### Section 1: Scope
 - **1.1 Identification**: Extract system name, version, identifiers from PRD/Product Brief
 - **1.2 System overview**: Summarize system purpose, nature, and stakeholders
-- **1.3 Document overview**: Describe this SSS document's purpose and contents
+- **1.3 Document overview**: Describe this SSS document's purpose, contents, and any security/privacy considerations
 
 ### Section 2: Referenced documents
-- List all project artifacts and external standards used
+- List all project artifacts and external standards used, with number, title, revision, and date
 
 ### Section 3: Requirements
 
-- **3.1 Required states and modes**: Identify system-level operational states from Architecture/PRD (e.g., operational, maintenance, degraded, emergency). If none, state so explicitly
-- **3.2 System capability requirements**: Map high-level PRD features and Product Brief goals to system capabilities. Each capability requirement (3.2.1, 3.2.2, etc.) must have:
+- **3.1 Required states and modes**: Identify system-level operational states from Architecture/PRD (e.g., operational, maintenance, degraded, emergency). If none, state so explicitly. If states/modes exist, correlate each requirement to the applicable states/modes.
+
+- **3.2 System capability requirements**: Map high-level PRD features and Product Brief goals to system capabilities (3.2.1, 3.2.2, etc.). Each requirement must have:
   - A unique identifier (SSS-CAP-001 format)
   - Clear, testable statement
-  - Performance parameters where applicable
-  - Behavior under error conditions
-- **3.3 System external interface requirements**: Map top-level external interfaces from Architecture — other systems, hardware, users, networks
-- **3.4 System internal interface requirements**: Map interfaces between major subsystems or components
-- **3.5 System internal data requirements**: System-level data stores, data flows between subsystems
-- **3.6 Adaptation requirements**: Installation and site-specific configuration needs
-- **3.7 Safety requirements**: System-level safety requirements
-- **3.8 Security and privacy requirements**: System-level security requirements from PRD
-- **3.9 System environment requirements**: Physical, regulatory, and operational environment constraints
-- **3.10 Computer resource requirements**: System-level hardware and infrastructure requirements
-- **3.11 System quality factors**: Reliability, availability, maintainability, portability requirements
-- **3.12 Design and implementation constraints**: Technology and methodology constraints
-- **3.13-3.18**: Additional requirement categories as defined in the template
+  - Parameters: response times, throughput, accuracy, capacity, priorities as applicable
+  - Error handling: behavior under unexpected, unallowed, or out-of-bounds conditions
+  - Provisions for continuity of operations in emergencies
+
+- **3.3 System external interface requirements**:
+  - **3.3.1 Interface identification and diagrams**: Identify all required external interfaces with project-unique identifiers. Designate interfacing entities by name, number, version. State which have fixed vs. developing characteristics. Provide interface diagrams.
+  - **3.3.x (per interface)**: For each external interface, specify requirements imposed on the system. Cover:
+    - **a.** Priority the system must assign the interface
+    - **b.** Type of interface (real-time data transfer, storage-and-retrieval, etc.)
+    - **c.** Data elements: names/identifiers, data types, sizes/formats, units, ranges, accuracy/precision, timing/frequency constraints, security constraints, sources and recipients
+    - **d.** Data element assemblies: records, messages, files, displays — names, structure, medium, characteristics, relationships, constraints
+    - **e.** Communication methods: links/media, message formatting, flow control, data transfer rates, routing, transmission services, security considerations
+    - **f.** Protocols: priority/layer, packeting, error control/recovery, synchronization, status/reporting
+    - **g.** Physical compatibility (dimensions, tolerances, loads, plug compatibility, voltages)
+
+- **3.4 System internal interface requirements**: Interfaces between major subsystems. If left to design or component specs, state so. If requirements exist, follow 3.3 topics.
+
+- **3.5 System internal data requirements**: System-level data stores, data flows between subsystems. If left to design or component specs, state so.
+
+- **3.6 Adaptation requirements**: Installation and site-specific configuration needs, operational parameters that may vary
+
+- **3.7 Safety requirements**: Requirements for preventing/minimizing unintended hazards to personnel, property, and environment. Include nuclear component requirements if applicable.
+
+- **3.8 Security and privacy requirements**: Security/privacy environment, type/degree of protection, risks, safeguards, policy, accountability, certification criteria
+
+- **3.9 System environment requirements**: Physical, regulatory, and operational environment constraints. For hardware-software systems: transportation, storage, operation conditions (wind, rain, temperature, shock, noise, electromagnetic radiation, explosions)
+
+- **3.10 Computer resource requirements**:
+  - **3.10.1 Computer hardware requirements**: Required hardware — processors, memory, I/O devices, auxiliary storage, communications/network equipment (number, type, size, capacity)
+  - **3.10.2 Computer hardware resource utilization requirements**: Maximum allowable utilization (% of processor, memory, I/O, storage, network capacity) with conditions for measurement
+  - **3.10.3 Computer software requirements**: Required software (OS, DBMS, network software, utilities) with nomenclature, version, and documentation references
+  - **3.10.4 Computer communications requirements**: Geographic locations, network topology, transmission techniques, data transfer rates, gateways, use times, data volume, time boundaries, peak volumes, diagnostics
+
+- **3.11 System quality factors**: Quantitative requirements for: functionality, reliability (e.g., MTBF for equipment), maintainability, availability, flexibility, portability, reusability, testability, usability
+
+- **3.12 Design and construction constraints**: Requirements constraining system design and construction. For hardware-software systems, include physical requirements:
+  - **a.** Architecture constraints: required subsystems, standard/military/existing components, Government-furnished property
+  - **b.** Design/construction standards, data standards, programming languages, workmanship requirements
+  - **c.** Physical characteristics: weight limits, dimensional limits, color, protective coatings, interchangeability, transportability, setup requirements
+  - **d.** Materials: allowed/prohibited materials, toxic material handling, electromagnetic radiation limits
+  - **e.** Nameplates, part marking, serial/lot number marking, other identifying markings
+  - **f.** Flexibility and expandability for anticipated growth, technology changes, threat changes, mission changes
+
+- **3.13 Personnel-related requirements**: Number of users, skill levels, duty cycles, training needs, human factors engineering (capabilities/limitations, foreseeable errors, critical indicator placement, adjustable workstations, error message color/duration, auditory signals)
+
+- **3.14 Training-related requirements**: Training devices and training materials to be included in the system
+
+- **3.15 Logistics-related requirements**: System maintenance, software support, transportation modes, supply-system requirements, facility impacts, equipment impacts
+
+- **3.16 Other requirements**: Additional requirements not covered above. Examples: system documentation requirements (specifications, drawings, manuals, test plans)
+
+- **3.17 Packaging requirements**: Requirements for packaging, labeling, and handling for delivery
+
+- **3.18 Precedence and criticality of requirements**: Order of precedence, criticality, or assigned weights. Identify requirements critical to safety, security, or privacy
 
 ### Section 4: Qualification provisions
-- For each requirement in Section 3, specify the qualification method: Demonstration, Test, Analysis, or Inspection
+For each requirement in Section 3, specify the qualification method(s). A table may be used:
+- **a.** Demonstration: Observable functional operation without instrumentation
+- **b.** Test: Operation using instrumentation or special test equipment
+- **c.** Analysis: Processing of accumulated data (reduction, interpolation, extrapolation)
+- **d.** Inspection: Visual examination of system components, documentation
+- **e.** Special qualification methods: Special tools, techniques, procedures, facilities, acceptance limits, standard samples, preproduction samples, pilot models/lots
 
 ### Section 5: Requirements traceability
-- **5.a**: For subsystem specs, map each requirement to parent system requirements
-- **5.b**: Map parent requirements to subsystem requirements that address them
+- For **system-level specifications**: This paragraph does not apply (state so).
+- For **subsystem-level specifications**:
+  - **5.a**: Map each subsystem requirement to the system requirements it addresses. Note: some requirements may trace to "system implementation" or system design decisions.
+  - **5.b**: Map each system requirement allocated to this subsystem to the subsystem requirements that address it. All allocated requirements shall be accounted for.
 
 ### Section 6: Notes
-- Glossary of terms, acronyms, and abbreviations
+- Alphabetical listing of all acronyms, abbreviations, and their meanings
+- Glossary of terms and definitions
+
+### Appendix A
+- Include any supplementary material (requirement matrices, charts, classified data) that supports the main body
 
 ## Step 4 — Validate
 
 Before presenting to the user, verify:
-- All template sections are populated or marked "Not applicable" with justification
+- All template sections (1-6 and Appendix A) are populated or marked "Not applicable" with justification
 - Requirements are at the system level (not CSCI/software level)
 - Every requirement has a unique identifier and is testable
-- Qualification methods are specified for all requirements
+- External interfaces (3.3.x) cover all seven categories (a through g) where applicable
+- Computer resource requirements (3.10) has all four subsections (3.10.1-3.10.4)
+- Design constraints (3.12) cover items a through f including physical requirements where applicable
+- Qualification methods are specified for all requirements including special methods (4.e)
+- Section 5 correctly handles system vs. subsystem distinction
 - Document is written in {document_output_language}
 
 ## Step 5 — Review
 
 Present the complete document to {user_name} for review.
 Highlight any sections where information was inferred or assumptions were made.
+Specifically ask about:
+- Are all system capabilities captured?
+- Are the interface requirements (3.3) accurate and complete?
+- Are there physical or environmental constraints not captured in 3.9 and 3.12?
+- Is the precedence/criticality ranking (3.18) correct?
+
 Offer to refine any section based on feedback.
 
 ## Step 6 — Save
@@ -92,5 +169,6 @@ Write the final document to:
 Confirm the file was saved and display a summary of:
 - Total system requirements identified
 - Number of capabilities documented
+- Number of interfaces specified
 - Qualification methods assigned
 - Any sections marked "Not applicable"

package/lib/bmad-workflows/mil498/std/instructions.md

@@ -20,6 +20,31 @@ Search the project for the following artifacts. Communicate in {communication_la
 
 If **required** artifacts are missing, warn the user and ask whether to proceed with available data or stop.
 
+### Document Dependencies
+
+The STD defines test descriptions that verify requirements specified in the SRS. It should be generated after both the SSDD and the SRS for the CSCI being tested.
+
+| Predecessor | Relationship | Search Pattern |
+|-------------|-------------|----------------|
+| SRS (Software Requirements Specification) | **Required** — provides the requirements that tests must verify | `**/SRS.md`, `**/SRS-*.md` |
+| SSDD (System/Subsystem Design Description) | **Required** — provides system context and CSCI decomposition | `**/SSDD.md` |
+| SDD (Software Design Description) | Recommended — provides design details useful for test planning | `**/SDD.md`, `**/SDD-*.md` |
+
+If the SRS has NOT been generated yet, **alert {user_name}**: "The SRS has not been generated yet. The STD needs the SRS to know which requirements must be verified by tests. Would you like to proceed without the SRS, or generate the SRS first?"
+
+If the SSDD has NOT been generated yet, **alert {user_name}**: "The SSDD has not been generated yet. The STD benefits from the system design context in the SSDD. Would you like to proceed without it, or generate the SSDD first?"
+
+If predecessor documents exist, they MUST be loaded and used as primary inputs. Test cases MUST trace back to specific SRS requirements.
+
+### CSCI/System Scoping
+
+Ask {user_name}: **"Is this STD for CSCI-level testing or system-level testing? If CSCI-level, which CSCI?"**
+
+- For CSCI-level testing: requirements come from the CSCI's SRS
+- For system-level testing: requirements come from the SSS
+
+If the SSDD exists, present the list of CSCIs and ask the user to select scope.
+
 ## Step 2 — Load Template
 
 Read the STD template from:
@@ -29,7 +54,7 @@ This defines the required DID sections and content expectations for each paragra
 
 ## Step 3 — Generate Document
 
-Write the document in {document_output_language}, populating each template section:
+Write the document in {document_output_language}, populating each template section. **Important**: Safety precautions (marked by WARNING or CAUTION) and security/privacy considerations shall be included as applicable throughout Sections 3 and 4.
 
 ### Section 1: Scope
 - **1.1 Identification**: Extract system and software identifiers from PRD/Architecture
@@ -37,52 +62,122 @@ Write the document in {document_output_language}, populating each template secti
 - **1.3 Document overview**: Describe this STD document's purpose and contents
 
 ### Section 2: Referenced documents
-- List all project artifacts, test standards, and other references used
+- List all project artifacts, test standards, and other references with number, title, revision, and date
 
 ### Section 3: Test preparations
 
-For each test identified, provide (organized as 3.x subsections):
+Organize as 3.x subsections, one per test. For each test (3.x), provide a brief description and the following:
 
-- **3.x.1 Hardware preparation**: Test environment hardware requirements from Architecture — servers, devices, network configuration. Include setup procedures
-- **3.x.2 Software preparation**: Test environment software requirements — OS, databases, dependencies, test frameworks. Include installation and configuration steps
-- **3.x.3 Other pre-test preparations**: Test data setup, user accounts, external service mocks, environment variables. Include any prerequisites that must be satisfied
-
-### Section 4: Test descriptions
+- **3.x.1 Hardware preparation**: Procedures to prepare hardware for the test:
+  - **a.** Specific hardware to be used, identified by name and number
+  - **b.** Switch settings and cabling necessary to connect the hardware
+  - **c.** Diagrams showing hardware, interconnecting control, and data paths
+  - **d.** Step-by-step instructions for placing hardware in a state of readiness
+- **3.x.2 Software preparation**: Procedures to prepare software for the test:
+  - **a.** Specific software to be used in the test
+  - **b.** Storage medium of the item(s) under test
+  - **c.** Storage medium of related software (simulators, test drivers, databases)
+  - **d.** Instructions for loading software, including required sequence
+  - **e.** Instructions for software initialization common to more than one test case
+- **3.x.3 Other pre-test preparations**: Any other personnel actions, preparations, or procedures necessary (test data setup, user accounts, external service mocks, environment variables)
 
-For each test case (organized as 4.x subsections), derive from Story acceptance criteria and SRS requirements:
+When information duplicates another test's preparation, reference it rather than repeating it.
 
-- **4.x.1 Test identifier**: Unique identifier (STD-TEST-001 format)
-- **4.x.2 Test objective**: What requirement(s) this test verifies. Reference SRS requirement IDs if available
-- **4.x.3 Input data**: Specific test inputs, preconditions, and initial state
-- **4.x.4 Expected results**: Precise expected outputs, state changes, and behaviors
-- **4.x.5 Criteria for evaluating results**: Pass/fail criteria
-- **4.x.6 Test procedure**: Step-by-step procedure to execute the test
-- **4.x.7 Assumptions and constraints**: Any assumptions about the test environment
+### Section 4: Test descriptions
 
-Group test cases by capability/feature (mapping to Epics) for clarity.
+Organize as a **two-level hierarchy**: 4.x per test, then 4.x.y per test case within each test. Group test cases by capability/feature (mapping to Epics) for clarity.
+
+For each test (4.x), identify the test by project-unique identifier. Then for each test case (4.x.y), provide:
+
+- **4.x.y.1 Requirements addressed**: Identify the CSCI or system requirements addressed by this test case. Reference specific SRS requirement IDs (e.g., SRS-CAP-001). (Alternatively, this traceability may be provided in Section 5.a.)
+
+- **4.x.y.2 Prerequisite conditions**: Conditions that must be established prior to the test case:
+  - **a.** Hardware and software configuration
+  - **b.** Flags, initial breakpoints, pointers, control parameters, or initial data to be set/reset
+  - **c.** Preset hardware conditions or electrical states
+  - **d.** Initial conditions for timing measurements
+  - **e.** Conditioning of the simulated environment
+  - **f.** Other special conditions peculiar to the test case
+
+- **4.x.y.3 Test inputs**: Test inputs necessary for the test case:
+  - **a.** Name, purpose, and description (range of values, accuracy) of each test input
+  - **b.** Source of the test input and method for selecting it
+  - **c.** Whether the test input is real or simulated
+  - **d.** Time or event sequence of test input
+  - **e.** How input data will be controlled to:
+    1. Test with minimum/reasonable number of data types and values
+    2. Exercise with a range of valid data (overload, saturation, worst-case)
+    3. Exercise with invalid data types and values (error handling)
+    4. Permit retesting if necessary
+
+- **4.x.y.4 Expected test results**: All expected results — both intermediate and final results
+
+- **4.x.y.5 Criteria for evaluating results**: Criteria for intermediate and final results:
+  - **a.** Range or accuracy over which output can vary and still be acceptable
+  - **b.** Minimum number of input/output combinations that constitute acceptable results
+  - **c.** Maximum/minimum allowable test duration (time or number of events)
+  - **d.** Maximum number of interrupts, halts, or system breaks that may occur
+  - **e.** Allowable severity of processing errors
+  - **f.** Conditions under which the result is inconclusive and retesting is needed
+  - **g.** Conditions indicating irregularities in input data, test database, or procedures
+  - **h.** Allowable indications of control, status, and results readiness for next test case
+  - **i.** Additional criteria not covered above
+
+- **4.x.y.6 Test procedure**: Defined as individually numbered steps in sequential order:
+  - **a.** Test operator actions and equipment operation for each step, including commands to:
+    1. Initiate the test case and apply test inputs
+    2. Inspect test conditions
+    3. Perform interim evaluations of test results
+    4. Record data
+    5. Halt or interrupt the test case
+    6. Request data dumps or other aids
+    7. Modify the database/data files
+    8. Repeat the test case if unsuccessful
+    9. Apply alternate modes as required
+    10. Terminate the test case
+  - **b.** Expected result and evaluation criteria for each step
+  - **c.** If addressing multiple requirements, which steps address which requirements
+  - **d.** Actions to follow in event of program stop or error (recording critical data, halting time-sensitive software, collecting records)
+  - **e.** Procedures for reducing and analyzing test results (detect output, identify media/location, evaluate for continuation, evaluate against required output)
+
+- **4.x.y.7 Assumptions and constraints**: Assumptions made and constraints imposed (limitations on timing, interfaces, equipment, personnel, database). If waivers/exceptions to limits are approved, address their effects.
 
 ### Section 5: Requirements traceability
-- Map each test case to the SRS requirement(s) it verifies
-- Ensure every SRS requirement has at least one associated test case
-- Identify any requirements that cannot be tested and explain why
+- **5.a**: Map each test case to the system or CSCI requirements it addresses. If a test case addresses multiple requirements, indicate which test procedure steps address which requirements.
+- **5.b**: Map each requirement covered by this STD to the test case(s) that address it. For CSCI testing, trace from each SRS requirement. For system testing, trace from each SSS requirement. Indicate specific test procedure steps where applicable.
+- Ensure every requirement has at least one associated test case. Identify any requirements that cannot be tested and explain why.
 
 ### Section 6: Notes
-- Glossary of test terminology and abbreviations
+- Alphabetical listing of all acronyms, abbreviations, and their meanings
+- Glossary of test terminology
 - References to test automation frameworks or tools used
 
+### Appendix A
+- Test procedures may be included as an appendix for convenience in document maintenance
+- Include any supplementary material (test data sets, detailed configurations)
+
 ## Step 4 — Validate
 
 Before presenting to the user, verify:
-- All template sections are populated or marked "Not applicable" with justification
+- All template sections (1-6 and Appendix A) are populated or marked "Not applicable" with justification
+- Test hierarchy is preserved: 4.x (test) → 4.x.y (test case) → 4.x.y.1-7 (details)
+- Every test case has all seven sub-items (4.x.y.1 through 4.x.y.7)
 - Every test case has a unique identifier and clear pass/fail criteria
-- Requirements traceability is complete (all requirements covered)
+- Requirements traceability is complete — every SRS/SSS requirement has at least one test case
 - Test procedures are detailed enough to be repeatable
+- Safety precautions and security considerations are included where applicable
 - Document is written in {document_output_language}
 
 ## Step 5 — Review
 
 Present the complete document to {user_name} for review.
 Highlight any requirements without test coverage.
+Specifically ask about:
+- Are the test preparations complete for the target environment?
+- Are the evaluation criteria (4.x.y.5) realistic and measurable?
+- Are there additional test cases needed for edge cases or error scenarios?
+- Are the test procedures detailed enough to be executed by someone unfamiliar with the system?
+
 Offer to refine any section based on feedback.
 
 ## Step 6 — Save
@@ -91,7 +186,8 @@ Write the final document to:
 `{output_folder}/planning-artifacts/STD.md`
 
 Confirm the file was saved and display a summary of:
-- Total number of test cases defined
+- Total number of tests (4.x level)
+- Total number of test cases (4.x.y level)
 - Requirements coverage percentage
 - Any untestable requirements identified
 - Any sections marked "Not applicable"