diff --git a/ASG_Framework.md b/ASG_Framework.md index a34091c..2877c38 100644 --- a/ASG_Framework.md +++ b/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. -- Non-Functional Requirements covering performance, scalability, availability, reliability, and privacy. +- **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 (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 | -|-------------------|----------------|-------------------|-------------| -| Comparison table UI | FR-101 | SD-2.1 | Display wines in table format | -| Filtering | FR-102 | SD-2.2 | Filter wines by criteria | -| Sorting | FR-103 | SD-2.3 | Sort wines by any column | -| Real-time updates | NFR-201 | SD-2.4 | Updates appear within 100ms | -| Export comparison | FR-201 | SD-2.5 | Export comparison to PDF/CSV | +| Solution Component | Requirement ID | Decision ID | Description | +|-------------------|----------------|-------------|-------------| +| Comparison table UI | FR-101 | SD-001-D1 | Display wines in table format | +| Filtering | FR-102 | SD-001-D2 | Filter wines by criteria | +| Sorting | FR-103 | SD-001-D3 | Sort wines by any column | +| Real-time updates | NFR-201 | SD-001-D4 | Updates appear within 100ms | +| Export comparison | FR-201 | SD-001-D5 | Export comparison to PDF/CSV | ### Specification Template