diff --git a/docs/requirements/AGENT.md b/docs/requirements/AGENT.md new file mode 100644 index 0000000..38741c6 --- /dev/null +++ b/docs/requirements/AGENT.md @@ -0,0 +1,28 @@ +# Requirements Documentation Instructions + +When creating or editing requirement documents: + +1. **Use the template** at `docs/requirements/TEMPLATE_SHR.md` for Stakeholder Requirement + +2. **Use the template** at `docs/requirements/TEMPLATE_SWR.md` for Software Requirements + +2. **Set Requirement Type** using this mapping: + +| Requirement Type | Value | +| ----------------------------- | --------------------------------------- | +| USE_CASE | Software requirement (regulatory) | +| TECHNICAL | Stakeholder requirement (system) | +| FUNCTIONAL | Software requirement (user) | +| INTERFACES | Stakeholder requirement (performance) | +| REGULATORY | Software requirement (system) | +| ENVIRONMENT | Stakeholder requirement (user) | +| SOFTWARE_IO | Software requirement (performance) | +| DOCUMENTATION | Stakeholder requirement (science) | +| FAULT_HANDLING | Stakeholder requirement (business) | +| SOFTWARE_SYSTEM | Stakeholder requirement (cybersecurity) | +| USER_MAINTENANCE | Software requirement (other) | +| DATA_AND_DATABASES | Software requirement (cybersecurity) | +| EXTERNAL_INTERFACES | Stakeholder requirement (regulatory) | +| ACCOMPANYING_DOCUMENTS | Software requirement (business) | +| USER_INTERFACE_SPECIFICATION | Software requirement (user interface) | +| ESSENTIAL_FUNCTION_PROTECTION | Software requirement (science) | \ No newline at end of file diff --git a/docs/requirements/SHR-APP-DISCOVERY.md b/docs/requirements/SHR-APP-DISCOVERY.md new file mode 100644 index 0000000..77915a1 --- /dev/null +++ b/docs/requirements/SHR-APP-DISCOVERY.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-APP-DISCOVERY +itemTitle: Application Discovery +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to discover available AI applications and their versions. diff --git a/docs/requirements/SHR-APP-EXEC.md b/docs/requirements/SHR-APP-EXEC.md new file mode 100644 index 0000000..c8bbcf4 --- /dev/null +++ b/docs/requirements/SHR-APP-EXEC.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-APP-EXEC +itemTitle: Application Execution Access +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to execute AI applications on slide data to generate analytical insights. diff --git a/docs/requirements/SHR-APP-RESULTS.md b/docs/requirements/SHR-APP-RESULTS.md new file mode 100644 index 0000000..c233866 --- /dev/null +++ b/docs/requirements/SHR-APP-RESULTS.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-APP-RESULTS +itemTitle: Application Results Access +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to access and retrieve results generated from AI application runs. diff --git a/docs/requirements/SHR-APP-RUN-MGMT.md b/docs/requirements/SHR-APP-RUN-MGMT.md new file mode 100644 index 0000000..c2bb5dd --- /dev/null +++ b/docs/requirements/SHR-APP-RUN-MGMT.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-APP-RUN-MGMT +itemTitle: Application Run Management +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to monitor status and manage the lifecycle of their AI application runs. diff --git a/docs/requirements/SHR-AUTH.md b/docs/requirements/SHR-AUTH.md new file mode 100644 index 0000000..096d480 --- /dev/null +++ b/docs/requirements/SHR-AUTH.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-AUTH +itemTitle: Authenticated Platform Access +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: SECURITY +--- + + + +## Description + +Access to the Aignostics Platform shall require valid user authentication credentials. diff --git a/docs/requirements/SHR-ERROR-COMM.md b/docs/requirements/SHR-ERROR-COMM.md new file mode 100644 index 0000000..dddee56 --- /dev/null +++ b/docs/requirements/SHR-ERROR-COMM.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-ERROR-COMM +itemTitle: Error Communication +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall receive clear information when operations fail. diff --git a/docs/requirements/SWR-APP-DISCOVERY-DETAILS.md b/docs/requirements/SWR-APP-DISCOVERY-DETAILS.md new file mode 100644 index 0000000..a3590e9 --- /dev/null +++ b/docs/requirements/SWR-APP-DISCOVERY-DETAILS.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-DISCOVERY-DETAILS +itemTitle: Application Details +itemHasParent: SHR-APP-DISCOVERY +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide application identification, description, and regulatory compliance information for each retrieved application. diff --git a/docs/requirements/SWR-APP-DISCOVERY-LIST.md b/docs/requirements/SWR-APP-DISCOVERY-LIST.md new file mode 100644 index 0000000..c997138 --- /dev/null +++ b/docs/requirements/SWR-APP-DISCOVERY-LIST.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-DISCOVERY-LIST +itemTitle: Application List Retrieval +itemHasParent: SHR-APP-DISCOVERY +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve all available AI applications accessible to the authenticated user. diff --git a/docs/requirements/SWR-APP-DISCOVERY-VERSION-DETAILS.md b/docs/requirements/SWR-APP-DISCOVERY-VERSION-DETAILS.md new file mode 100644 index 0000000..6b337f7 --- /dev/null +++ b/docs/requirements/SWR-APP-DISCOVERY-VERSION-DETAILS.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-DISCOVERY-VERSION-DETAILS +itemTitle: Version Details +itemHasParent: SHR-APP-DISCOVERY +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide version identification, change history, input requirements, and output specifications for each retrieved version. diff --git a/docs/requirements/SWR-APP-DISCOVERY-VERSION-LIST.md b/docs/requirements/SWR-APP-DISCOVERY-VERSION-LIST.md new file mode 100644 index 0000000..f5cca99 --- /dev/null +++ b/docs/requirements/SWR-APP-DISCOVERY-VERSION-LIST.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-DISCOVERY-VERSION-LIST +itemTitle: Version List Retrieval +itemHasParent: SHR-APP-DISCOVERY +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve all versions for a specified application. diff --git a/docs/requirements/SWR-APP-EXEC-INPUT-ARTIFACT.md b/docs/requirements/SWR-APP-EXEC-INPUT-ARTIFACT.md new file mode 100644 index 0000000..b77c0d0 --- /dev/null +++ b/docs/requirements/SWR-APP-EXEC-INPUT-ARTIFACT.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-EXEC-INPUT-ARTIFACT +itemTitle: Input Artifact Specification +itemHasParent: SHR-APP-EXEC +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall accept input artifacts containing artifact name, download URL, and metadata for each item in the run request. diff --git a/docs/requirements/SWR-APP-EXEC-REQUEST-VALIDATION.md b/docs/requirements/SWR-APP-EXEC-REQUEST-VALIDATION.md new file mode 100644 index 0000000..4a79fdc --- /dev/null +++ b/docs/requirements/SWR-APP-EXEC-REQUEST-VALIDATION.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-EXEC-REQUEST-VALIDATION +itemTitle: Request Validation +itemHasParent: SHR-APP-EXEC +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall validate run request format before submission to the platform. diff --git a/docs/requirements/SWR-APP-EXEC-RUN-CREATION.md b/docs/requirements/SWR-APP-EXEC-RUN-CREATION.md new file mode 100644 index 0000000..af9d37a --- /dev/null +++ b/docs/requirements/SWR-APP-EXEC-RUN-CREATION.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-EXEC-RUN-CREATION +itemTitle: Application Run Creation +itemHasParent: SHR-APP-EXEC +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall create application runs with specified application version, input items, and item- and run metadata and return a unique run identifier upon successful creation. diff --git a/docs/requirements/SWR-APP-RESULTS-ARTIFACT-STATUS.md b/docs/requirements/SWR-APP-RESULTS-ARTIFACT-STATUS.md new file mode 100644 index 0000000..7b181fa --- /dev/null +++ b/docs/requirements/SWR-APP-RESULTS-ARTIFACT-STATUS.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-RESULTS-ARTIFACT-STATUS +itemTitle: Artifact Status Information +itemHasParent: SHR-APP-RESULTS +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide execution state, download availability, termination status, and error details for each output artifact. diff --git a/docs/requirements/SWR-APP-RESULTS-ITEM-STATUS.md b/docs/requirements/SWR-APP-RESULTS-ITEM-STATUS.md new file mode 100644 index 0000000..a7c1050 --- /dev/null +++ b/docs/requirements/SWR-APP-RESULTS-ITEM-STATUS.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-RESULTS-ITEM-STATUS +itemTitle: Item Status Information +itemHasParent: SHR-APP-RESULTS +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide execution state, output availability, termination status, and error details for each item. diff --git a/docs/requirements/SWR-APP-RESULTS-RETRIEVE-ITEMS.md b/docs/requirements/SWR-APP-RESULTS-RETRIEVE-ITEMS.md new file mode 100644 index 0000000..babd99c --- /dev/null +++ b/docs/requirements/SWR-APP-RESULTS-RETRIEVE-ITEMS.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-RESULTS-RETRIEVE-ITEMS +itemTitle: Retrieve Run Items +itemHasParent: SHR-APP-RESULTS +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve items and their associated output artifacts for a specified application run by run ID. diff --git a/docs/requirements/SWR-APP-RUN-MGMT-CANCEL.md b/docs/requirements/SWR-APP-RUN-MGMT-CANCEL.md new file mode 100644 index 0000000..805b763 --- /dev/null +++ b/docs/requirements/SWR-APP-RUN-MGMT-CANCEL.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-RUN-MGMT-CANCEL +itemTitle: Cancel Application Run +itemHasParent: SHR-APP-RUN-MGMT +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall enable users to cancel a running or queued application run by run ID. diff --git a/docs/requirements/SWR-APP-RUN-MGMT-DEADLINE.md b/docs/requirements/SWR-APP-RUN-MGMT-DEADLINE.md new file mode 100644 index 0000000..99bfc7a --- /dev/null +++ b/docs/requirements/SWR-APP-RUN-MGMT-DEADLINE.md @@ -0,0 +1,14 @@ +--- +itemId: SWR-APP-RUN-MGMT-DEADLINE +itemTitle: Run Deadline Specification +itemHasParent: SHR-APP-RUN-MGMT +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + + +System shall accept optional deadline timestamp when creating application runs to specify when the Platform API should automatically cancel the run if not completed. diff --git a/docs/requirements/SWR-APP-RUN-MGMT-DETAILS.md b/docs/requirements/SWR-APP-RUN-MGMT-DETAILS.md new file mode 100644 index 0000000..28830ec --- /dev/null +++ b/docs/requirements/SWR-APP-RUN-MGMT-DETAILS.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-RUN-MGMT-DETAILS +itemTitle: Retrieve Run Details +itemHasParent: SHR-APP-RUN-MGMT +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve detailed information for a specific application run by run ID. diff --git a/docs/requirements/SWR-APP-RUN-MGMT-DUE-DATE.md b/docs/requirements/SWR-APP-RUN-MGMT-DUE-DATE.md new file mode 100644 index 0000000..5d413a9 --- /dev/null +++ b/docs/requirements/SWR-APP-RUN-MGMT-DUE-DATE.md @@ -0,0 +1,14 @@ +--- +itemId: SWR-APP-RUN-MGMT-DUE-DATE +itemTitle: Run Due Date Specification +itemHasParent: SHR-APP-RUN-MGMT +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + + +System shall accept optional due date timestamp when creating application runs to specify the expected completion time. diff --git a/docs/requirements/SWR-APP-RUN-MGMT-LIST.md b/docs/requirements/SWR-APP-RUN-MGMT-LIST.md new file mode 100644 index 0000000..03159d5 --- /dev/null +++ b/docs/requirements/SWR-APP-RUN-MGMT-LIST.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-APP-RUN-MGMT-LIST +itemTitle: List Application Runs +itemHasParent: SHR-APP-RUN-MGMT +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve a list of application runs with optional filtering by application ID and application version. diff --git a/docs/requirements/SWR-AUTH-AUTO-REFRESH.md b/docs/requirements/SWR-AUTH-AUTO-REFRESH.md new file mode 100644 index 0000000..c27b406 --- /dev/null +++ b/docs/requirements/SWR-AUTH-AUTO-REFRESH.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-AUTH-AUTO-REFRESH +itemTitle: Automatic Token Refresh +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall automatically refresh access tokens and retry failed API requests when authentication fails and valid refresh tokens are available. diff --git a/docs/requirements/SWR-AUTH-CODE-FLOW.md b/docs/requirements/SWR-AUTH-CODE-FLOW.md new file mode 100644 index 0000000..d68ac08 --- /dev/null +++ b/docs/requirements/SWR-AUTH-CODE-FLOW.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-AUTH-CODE-FLOW +itemTitle: Secure Authorisation Code Authentication +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall support secure authorization code-based authentication flow with cryptographic protection against authorization code interception attacks. diff --git a/docs/requirements/SWR-AUTH-CUSTOM-PROVIDER.md b/docs/requirements/SWR-AUTH-CUSTOM-PROVIDER.md new file mode 100644 index 0000000..dc687b4 --- /dev/null +++ b/docs/requirements/SWR-AUTH-CUSTOM-PROVIDER.md @@ -0,0 +1,12 @@ +--- +itemId: SWR-AUTH-CUSTOM-PROVIDER +itemTitle: Custom Token Provider +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +--- + + + +SDK shall accept user-provided token functions for obtaining access tokens. diff --git a/docs/requirements/SWR-AUTH-SECURE-STORAGE.md b/docs/requirements/SWR-AUTH-SECURE-STORAGE.md new file mode 100644 index 0000000..1d72b1b --- /dev/null +++ b/docs/requirements/SWR-AUTH-SECURE-STORAGE.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-AUTH-SECURE-STORAGE +itemTitle: Secure Token Storage +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall store authentication tokens with protection against unauthorized access. diff --git a/docs/requirements/SWR-AUTH-TOKEN-BASED.md b/docs/requirements/SWR-AUTH-TOKEN-BASED.md new file mode 100644 index 0000000..5a742ff --- /dev/null +++ b/docs/requirements/SWR-AUTH-TOKEN-BASED.md @@ -0,0 +1,12 @@ +--- +itemId: SWR-AUTH-TOKEN-BASED +itemTitle: Token-Based Authentication +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +--- + + + +System shall authenticate API requests using access tokens. diff --git a/docs/requirements/SWR-AUTH-TOKEN-REMOVAL.md b/docs/requirements/SWR-AUTH-TOKEN-REMOVAL.md new file mode 100644 index 0000000..4e4a531 --- /dev/null +++ b/docs/requirements/SWR-AUTH-TOKEN-REMOVAL.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-AUTH-TOKEN-REMOVAL +itemTitle: Token Removal +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (user) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall enable users to remove stored authentication tokens. diff --git a/docs/requirements/SWR-AUTH-VALIDATION.md b/docs/requirements/SWR-AUTH-VALIDATION.md new file mode 100644 index 0000000..c3afeed --- /dev/null +++ b/docs/requirements/SWR-AUTH-VALIDATION.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-AUTH-VALIDATION +itemTitle: Authentication Validation +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall reject API requests that do not include a valid access token. diff --git a/docs/requirements/SWR-ERROR-COMM-CLASSIFICATION.md b/docs/requirements/SWR-ERROR-COMM-CLASSIFICATION.md new file mode 100644 index 0000000..8087438 --- /dev/null +++ b/docs/requirements/SWR-ERROR-COMM-CLASSIFICATION.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-ERROR-COMM-CLASSIFICATION +itemTitle: Error Classification +itemHasParent: SHR-ERROR-COMM +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall assign a unique error code to each error to enable programmatic error handling and differentiation between error types. diff --git a/docs/requirements/SWR-ERROR-COMM-CLI-OUTPUT.md b/docs/requirements/SWR-ERROR-COMM-CLI-OUTPUT.md new file mode 100644 index 0000000..2770769 --- /dev/null +++ b/docs/requirements/SWR-ERROR-COMM-CLI-OUTPUT.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-ERROR-COMM-CLI-OUTPUT +itemTitle: CLI Error Output +itemHasParent: SHR-ERROR-COMM +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: CLI +--- + + + +CLI shall write error messages to standard error stream and provide machine-readable operation status through standard exit mechanisms. diff --git a/docs/requirements/SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md b/docs/requirements/SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md new file mode 100644 index 0000000..e292422 --- /dev/null +++ b/docs/requirements/SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT +itemTitle: Error Diagnostic Context +itemHasParent: SHR-ERROR-COMM +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall include diagnostic context in errors including protocol-specific status information for API failures and original error details for debugging. diff --git a/docs/requirements/SWR-ERROR-COMM-MESSAGES.md b/docs/requirements/SWR-ERROR-COMM-MESSAGES.md new file mode 100644 index 0000000..2f87561 --- /dev/null +++ b/docs/requirements/SWR-ERROR-COMM-MESSAGES.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-ERROR-COMM-MESSAGES +itemTitle: Error Messages +itemHasParent: SHR-ERROR-COMM +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide error messages that describe the failure cause and corrective action where applicable. diff --git a/docs/requirements/TEMPLATE_SHR.md b/docs/requirements/TEMPLATE_SHR.md new file mode 100644 index 0000000..e8930c9 --- /dev/null +++ b/docs/requirements/TEMPLATE_SHR.md @@ -0,0 +1,167 @@ +# SHR Template - Stakeholder Requirement + +**Purpose**: Use this template to create Stakeholder Requirements (SHR) - high-level requirements that describe what stakeholders need from the system. + +## Template Structure + +```markdown +--- +itemId: SHR-[DESCRIPTIVE-NAME] +itemTitle: [Brief Descriptive Title] +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: [FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABILITY] +--- + + + +## Description + +[Detailed description of the stakeholder requirement. This should clearly state what users/stakeholders need to be able to do or what the system needs to provide. Write in complete sentences describing the capability or need from the stakeholder's perspective.] +``` + +## Field Definitions + +### YAML Frontmatter (Required) + +- **itemId**: Unique identifier following pattern `SHR-[DESCRIPTIVE-NAME]` + - `[DESCRIPTIVE-NAME]`: Hyphenated descriptive identifier using module prefix and feature name + - Should be clear, concise, and self-documenting + - Use uppercase with hyphens (kebab-case in uppercase) + - Common module prefixes: APP, AUTH, SYSTEM, BUCKET, DATASET, ERROR, API + - Example: `SHR-APP-DISCOVERY`, `SHR-AUTH`, `SHR-ERROR-COMM`, `SHR-APP-RUN-MGMT` + +- **itemTitle**: Short, descriptive title (3-8 words recommended) + - Should be clear and specific + - Use title case + - Example: "Application Run Management", "System Health Monitoring and Observability" + +- **itemType**: Always set to `Requirement` for requirements documents + +- **Requirement type**: Choose one based on the nature of the requirement: + - `FUNCTIONAL`: Requirements describing specific system functions or capabilities (most common) + - `REGULATORY`: Requirements derived from regulations, standards, or compliance needs + - `PERFORMANCE`: Requirements about system performance, speed, or efficiency + - `SECURITY`: Requirements about system security, access control, or data protection + - `USABILITY`: Requirements about user experience, accessibility, or ease of use + + Note: ENVIRONMENT type has been removed - use FUNCTIONAL for user workflows and system context requirements + +### Description Section (Required) + +- **Format**: Markdown heading level 2 (`## Description`) +- **Content**: 1-3 paragraphs describing the stakeholder requirement +- **Style**: + - Write from stakeholder/user perspective + - Use "Users shall be able to..." or "The system shall provide..." + - Be clear and specific about the capability or need + - Focus on WHAT is needed, not HOW it will be implemented + - Avoid technical implementation details + +## Examples + +### Example 1: User-Facing Capability +```markdown +--- +itemId: SHR-APP-DISCOVERY +itemTitle: Application Discovery +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to discover available AI applications and their versions. +``` + +### Example 2: Security Requirement +```markdown +--- +itemId: SHR-AUTH +itemTitle: Authenticated Platform Access +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: SECURITY +--- + + + +## Description + +Access to the Aignostics Platform shall require valid user authentication credentials. +``` + +### Example 3: Error Handling Requirement +```markdown +--- +itemId: SHR-ERROR-COMM +itemTitle: Error Communication +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall receive clear information when operations fail. +``` + +## Naming Conventions + +### Module Prefixes +Use clear, consistent module prefixes that reflect your system architecture: +- APP (for application-related features) +- AUTH (for authentication/authorization) +- SYSTEM (for system-wide capabilities) +- BUCKET (for storage management) +- DATASET (for data operations) +- ERROR (for error handling and communication) +- API (for API-specific requirements) +- USER (for user management) +- etc. + +### Descriptive Names +- Use hyphenated uppercase names (e.g., `SHR-APP-DISCOVERY`, `SHR-APP-RUN-MGMT`) +- Combine module prefix with feature name +- Keep names concise but descriptive +- Use common abbreviations where clear (MGMT for Management, EXEC for Execution, COMM for Communication) +- Example: `SHR-APP-DISCOVERY`, `SHR-AUTH`, `SHR-ERROR-COMM`, `SHR-APP-RESULTS` + +## Best Practices + +1. **Keep it High-Level**: SHRs describe stakeholder needs, not technical solutions +2. **User-Centric**: Write from the perspective of what users need to accomplish +3. **Complete**: Each SHR should be a complete, standalone capability description +4. **Verifiable**: Write requirements that can be verified through testing or demonstration +5. **Clear Scope**: Define the boundaries of what the requirement covers +6. **Parent-Child**: SHRs will have child SWR requirements that detail HOW to implement them + +## Validation Checklist + +Before finalizing an SHR, verify: +- [ ] itemId follows SHR-[DESCRIPTIVE-NAME] pattern (e.g., SHR-APP-DISCOVERY) +- [ ] itemTitle is clear and descriptive +- [ ] itemType is set to "Requirement" +- [ ] Requirement type is one of the valid values (FUNCTIONAL, SECURITY, etc.) +- [ ] Description section exists with ## heading +- [ ] Description explains WHAT stakeholders need (not HOW) +- [ ] Language is clear and unambiguous +- [ ] Requirement is testable/verifiable +- [ ] YAML frontmatter is properly formatted +- [ ] Optional comment included for original reference if migrating + +## Notes for AI Agents + +When generating SHR files: +1. Read the project documentation to understand modules and architecture +2. Identify high-level stakeholder needs and capabilities +3. Group related requirements under appropriate modules +4. Create one SHR file per stakeholder requirement +5. Ensure each SHR can be decomposed into multiple SWR requirements +6. Use consistent terminology throughout all requirements +7. Consider the user journey and workflows when defining requirements diff --git a/docs/requirements/TEMPLATE_SWR.md b/docs/requirements/TEMPLATE_SWR.md new file mode 100644 index 0000000..23f87ad --- /dev/null +++ b/docs/requirements/TEMPLATE_SWR.md @@ -0,0 +1,296 @@ +# SWR Template - Software Requirement + +**Purpose**: Use this template to create Software Requirements (SWR) - detailed technical requirements that implement stakeholder requirements (SHR). + +## Template Structure + +```markdown +--- +itemId: SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX] +itemTitle: [Brief Descriptive Title] +itemHasParent: SHR-[PARENT-NAME] +itemType: Requirement +# Software requirement (user|system) +Requirement type: [FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABILITY] +Layer: [System (backend logic)|User Interface (frontend)|GUI|CLI|API|Database|etc.] +--- + + + +[Detailed requirement description. Can be written as a plain statement or as a user story. Should clearly specify the technical implementation requirement.] +``` + +## Field Definitions + +### YAML Frontmatter (Required) + +- **itemId**: Unique identifier following pattern `SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX]` + - `[PARENT-NAME]`: The full descriptive name from parent SHR (e.g., APP-DISCOVERY, AUTH, ERROR-COMM) + - `[DESCRIPTIVE-SUFFIX]`: Short descriptive identifier for this specific requirement + - Use hyphenated uppercase names + - Example: `SWR-APP-DISCOVERY-LIST`, `SWR-APP-DISCOVERY-DETAILS`, `SWR-AUTH-TOKEN-BASED`, `SWR-ERROR-COMM-CLI-OUTPUT` + +- **itemTitle**: Short, descriptive title (3-8 words recommended) + - Should be specific about the technical requirement + - Use title case + - Example: "List Available Applications", "Accept Optional Run Name and Description" + +- **itemHasParent**: Reference to parent SHR using format `SHR-[PARENT-NAME]` + - Must match an existing SHR itemId exactly + - Example: `SHR-APP-DISCOVERY`, `SHR-AUTH`, `SHR-ERROR-COMM` + +- **itemType**: Always set to `Requirement` for requirements documents + +- **Software requirement comment**: Choose one: + - `# Software requirement (user)` - User-facing software requirements + - `# Software requirement (system)` - System-level software requirements + +- **Requirement type**: Choose one based on the nature of the requirement: + - `FUNCTIONAL`: Requirements describing specific system functions or operations + - `REGULATORY`: Requirements derived from regulations, standards, or compliance needs + - `PERFORMANCE`: Requirements about system performance, speed, or efficiency + - `SECURITY`: Requirements about system security, access control, or data protection + - `USABILITY`: Requirements about user experience, accessibility, or ease of use + +- **Layer**: (Optional) Specify the architectural layer: + - `System (backend logic)` - Backend business logic, services, APIs + - `User Interface (frontend)` - Frontend web/mobile interface + - `GUI` - Desktop GUI application + - `CLI` - Command-line interface + - `API` - API endpoints and contracts + - `Database` - Database schema and operations + - `System (frontend interface)` - Frontend system components + - Or any other layer relevant to your architecture + +### Requirement Description (Required) + +- **Format**: Direct text after YAML frontmatter (no heading) +- **Content**: 1-3 sentences describing the specific technical requirement +- **Style Options**: + + **Option 1 - Plain Statement** (most common): + ``` + System shall provide a list of available applications for user selection. + ``` + + **Option 2 - User Story Format**: + ``` + As a user, I expected the current health of Launchpad being always visible in the footer of the GUI so that I can ensure the system is operational. + ``` + + **Option 3 - Detailed Statement**: + ``` + System shall accept optional user-provided run name and description during application run submission. The system shall validate that run names do not exceed 100 characters and descriptions do not exceed 500 characters when provided, and shall store these metadata fields with the run record. + ``` + +- **Guidelines**: + - Be specific about technical implementation + - Include validation rules, constraints, or limits if applicable + - Use "System shall..." for system actions + - Use "As a user..." for user story format + - Focus on HOW the parent SHR will be implemented + - Include acceptance criteria when relevant + +## Examples + +### Example 1: Simple Backend Requirement +```markdown +--- +itemId: SWR-APP-DISCOVERY-LIST +itemTitle: List Available Applications +itemHasParent: SHR-APP-DISCOVERY +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide a list of available applications for user selection. +``` + +### Example 2: CLI Requirement +```markdown +--- +itemId: SWR-ERROR-COMM-CLI-OUTPUT +itemTitle: CLI Error Output +itemHasParent: SHR-ERROR-COMM +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: CLI +--- + + + +CLI shall write error messages to standard error stream and provide machine-readable operation status through standard exit mechanisms. +``` + +### Example 3: Authentication Requirement +```markdown +--- +itemId: SWR-AUTH-TOKEN-BASED +itemTitle: Token-Based Authentication +itemHasParent: SHR-AUTH +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +--- + + + +System shall authenticate API requests using access tokens. +``` + +### Example 4: Detailed Application Requirement +```markdown +--- +itemId: SWR-APP-DISCOVERY-DETAILS +itemTitle: Application Details +itemHasParent: SHR-APP-DISCOVERY +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide application identification, description, and regulatory compliance information for each retrieved application. +``` + +### Example 5: Request Validation Requirement +```markdown +--- +itemId: SWR-APP-EXEC-REQUEST-VALIDATION +itemTitle: Request Validation +itemHasParent: SHR-APP-EXEC +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall validate run request format before submission to the platform. +``` + +## Naming Conventions + +### itemId Pattern +`SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX]` + +**Structure**: +1. **Parent Name**: Must exactly match the parent SHR's descriptive name + - Example: If parent is `SHR-APP-DISCOVERY`, use `SWR-APP-DISCOVERY-*` + +2. **Descriptive Suffix**: Short identifier specific to this requirement + - Use descriptive keywords: LIST, DETAILS, CREATE, DELETE, VALIDATION, etc. + - Keep it concise but meaningful + - Use hyphens for multi-word suffixes + +**Examples**: +- `SWR-APP-DISCOVERY-LIST` (parent: SHR-APP-DISCOVERY) +- `SWR-APP-DISCOVERY-DETAILS` (parent: SHR-APP-DISCOVERY) +- `SWR-AUTH-TOKEN-BASED` (parent: SHR-AUTH) +- `SWR-ERROR-COMM-CLI-OUTPUT` (parent: SHR-ERROR-COMM) +- `SWR-APP-EXEC-REQUEST-VALIDATION` (parent: SHR-APP-EXEC) + +**Recommendation**: Use descriptive suffixes that clearly indicate the specific functionality being implemented. + +## Relationship to SHR + +Each SWR must: +1. Reference exactly one parent SHR via `itemHasParent` +2. Implement a specific aspect of that parent SHR +3. Be more detailed and technical than the parent SHR +4. Focus on HOW to implement WHAT the parent SHR describes + +**Example Breakdown**: +``` +SHR-APP-DISCOVERY: "Application Discovery" +├── SWR-APP-DISCOVERY-LIST: "List Available Applications" +├── SWR-APP-DISCOVERY-DETAILS: "Application Details" +├── SWR-APP-DISCOVERY-VERSION-LIST: "List Application Versions" +└── SWR-APP-DISCOVERY-VERSION-DETAILS: "Application Version Details" +``` + +## Layer Guidelines + +Choose the appropriate layer based on where the requirement is implemented: + +- **System (backend logic)**: Business logic, data processing, API services +- **User Interface (frontend)**: Web or mobile UI components and interactions +- **GUI**: Desktop graphical interface +- **CLI**: Command-line interface commands and options +- **API**: REST/GraphQL endpoints, request/response formats +- **Database**: Schema, queries, data persistence +- **Integration**: External system integrations +- **Infrastructure**: Deployment, scaling, monitoring + +**Note**: Layer field is optional but recommended for clarity. Omit if not applicable to your project. + +## Best Practices + +1. **Specificity**: SWRs should be specific enough to implement and test +2. **Traceability**: Always link to parent SHR via itemHasParent +3. **Granularity**: One SWR per distinct technical requirement +4. **Testability**: Write requirements that can be verified through automated or manual testing +5. **Completeness**: Include validation rules, constraints, error handling +6. **Clarity**: Use clear, unambiguous language +7. **Consistency**: Use consistent terminology with parent SHR and other SWRs + +## Common Patterns + +### Validation Requirements +```markdown +System shall validate that [field] does not exceed [limit] characters when provided, and shall [action] when validation fails. +``` + +### Data Operations +```markdown +System shall [action] [data] to/from [location] while [constraint/condition]. +``` + +### User Interface Requirements +```markdown +As a user, I expect [UI element] to [behavior] in [location] so that [benefit/reason]. +``` + +### Multi-Step Operations +```markdown +System shall [action1] at multiple [scope] levels: [option1], [option2], and [option3]. The system shall [action2] when [condition], and provide [output] with [details]. +``` + +## Validation Checklist + +Before finalizing an SWR, verify: +- [ ] itemId follows SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX] pattern +- [ ] itemId parent name exactly matches the parent SHR's name +- [ ] itemTitle is clear and descriptive +- [ ] itemHasParent references a valid SHR (exact match) +- [ ] itemType is set to "Requirement" +- [ ] Software requirement type (user|system) is specified +- [ ] Requirement type is one of the valid values +- [ ] Layer is specified (optional but recommended) +- [ ] Requirement description is clear and implementable +- [ ] Requirement is testable/verifiable +- [ ] YAML frontmatter is properly formatted +- [ ] Optional comment included for original reference if migrating +- [ ] Requirement implements part of the parent SHR + +## Notes for AI Agents + +When generating SWR files: +1. Always start by identifying the parent SHR +2. Break down the parent SHR into logical, implementable components +3. Create one SWR file per technical requirement +4. Ensure each SWR is specific enough to implement +5. Include validation rules and constraints where applicable +6. Use consistent terminology with parent SHR +7. Consider the full technical stack (frontend, backend, database, etc.) +8. Group related SWRs under the same parent SHR +9. Ensure completeness: all aspects of parent SHR should be covered by child SWRs +10. Maintain traceability: every SWR should clearly implement part of its parent SHR