update

ASG_Framework.md

@@ -34,19 +34,27 @@ This document defines the documentation framework for a software project. It est
 
 **Content Guidelines**:
 - User stories with clear acceptance criteria (As a X, I want Y so that Z)
-- Functional Requirements Documents with clear success metrics and KPIs.
+- **Functional Requirements (FR)**: Testable features with clear IDs (e.g., `FR-001`, `FR-101`). Each functional requirement must be linked to a measurable KPI in the success metrics section.
-- Non-Functional Requirements covering performance, scalability, availability, reliability, and privacy.
+- **Non-Functional Requirements (NFR)**: Qualities or constraints the system must have (performance, scalability, availability, reliability, security, privacy, observability). NFRs define *what kind of system* you need, not *what it does*.
+  - Example NFR: "System shall support 10K TPS" (requirement)
+  - Example KPI: "95th percentile latency <200ms" (measurable success metric)
+- **Success Metrics & KPIs**: Specific, measurable targets that validate whether requirements were met. KPIs are *measured after deployment*; NFRs are *defined before implementation*.
 - Boundary definitions that state what is in scope and out of scope.
 - Security requirements including threat model outcomes, authentication and authorization expectations, data classification, encryption requirements, and compliance controls.
 - Observability requirements specifying required telemetry, metrics, traces, logs, alerting thresholds, and retention policies.
 - Traceability Rule: Requirements must be self-contained (no cross-references to other docs as justification), but must include IDs (e.g., FR-001) so downstream artifacts (spec, UI spec, architecture) can trace back. All downstream documents MUST cite requirement IDs, but requirements themselves stand alone.
 
 **Best Practices**:
-- Link each requirement to a measurable KPI
+- **Link each requirement to a measurable KPI** — functional requirements should have explicit KPIs; non-functional requirements should have measurable thresholds
 - Keep requirements testable and verifiable
 - Maintain backward compatibility with existing requirements
 - Review and update requirements as business context changes
 
+**NFR vs KPI Clarification**:
+- **NFR** is a *requirement* — it defines what quality or constraint the system must have (e.g., "System shall support 10K TPS", "99.9% monthly uptime", "TLS 1.3+ encryption")
+- **KPI** is a *measurement* — it's the actual data collected to verify if the NFR was met (e.g., "Peak traffic was 8.5K TPS", "MTTR was 8 minutes", "100% of connections use TLS 1.3")
+- NFRs tell you **what to build**; KPIs tell you **how well you built it**
+
 ---
 
 ### 2. Solution Design
@@ -72,7 +80,7 @@ This document defines the documentation framework for a software project. It est
 - Decision rationale: Explain why each major decision was made (e.g., "Chose NATS over Kafka for simpler ops", "Used server-side rendering for SEO")
 - Risk assessment: Identify potential risks and how they will be mitigated
 - Traceability: Link each solution component to specific requirement ID(s) (e.g., FR-001, NFR-201) that it addresses
-- Solution Design IDs: Assign unique IDs to major decisions (e.g., `SD-2.1` for "Use NATS for async messaging") to enable specification traceability
+- Decision IDs: Assign unique IDs to major decisions (e.g., `SD-001-D1` for "Use NATS for async messaging") to enable specification traceability
 
 **Best Practices**:
 - Write solution design from the user's perspective first, then justify technical choices
@@ -447,7 +455,9 @@ Each documentation artifact has associated KPIs. Track these to ensure quality:
 ## 1. Business Context & Success Metrics
 - Business Goal
 - User Stories (with acceptance criteria)
-- KPIs & Targets (e.g., "99.95% availability", "<200ms p95 latency")
+- **Functional Requirements (FR)**: List each FR ID with its corresponding KPI target
+- **Non-Functional Requirements (NFR)**: Define quality/constraint requirements (e.g., "Support 10K TPS", "99.9% uptime", "TLS 1.3+")
+- **Success Metrics (KPIs)**: Define measurable targets that validate NFRs (e.g., "95th percentile latency <200ms", "MTTR <10min", "100% TLS 1.3")
 
 ## 2. Technical Boundaries
 - In Scope
@@ -562,13 +572,13 @@ Identify potential risks and mitigation strategies.
 
 Link each solution component to specific requirements and assign Solution Design IDs for specification traceability.
 
-| Solution Component | Requirement ID | Solution Design ID | Description |
+| Solution Component | Requirement ID | Decision ID | Description |
-|-------------------|----------------|-------------------|-------------|
+|-------------------|----------------|-------------|-------------|
-| Comparison table UI | FR-101 | SD-2.1 | Display wines in table format |
+| Comparison table UI | FR-101 | SD-001-D1 | Display wines in table format |
-| Filtering | FR-102 | SD-2.2 | Filter wines by criteria |
+| Filtering | FR-102 | SD-001-D2 | Filter wines by criteria |
-| Sorting | FR-103 | SD-2.3 | Sort wines by any column |
+| Sorting | FR-103 | SD-001-D3 | Sort wines by any column |
-| Real-time updates | NFR-201 | SD-2.4 | Updates appear within 100ms |
+| Real-time updates | NFR-201 | SD-001-D4 | Updates appear within 100ms |
-| Export comparison | FR-201 | SD-2.5 | Export comparison to PDF/CSV |
+| Export comparison | FR-201 | SD-001-D5 | Export comparison to PDF/CSV |
 
 
 ### Specification Template