diff --git a/ASG_Framework.md b/ASG_Framework.md index b324ce7..a34091c 100644 --- a/ASG_Framework.md +++ b/ASG_Framework.md @@ -52,6 +52,8 @@ This document defines the documentation framework for a software project. It est ### 2. Solution Design `solution-design.md` +**Document ID**: Each `solution-design.md` file should have a unique document ID (e.g., `SD-001`, `SD-002`) for cross-referencing. Use the format `SD-XXX` where `XXX` is a 3-digit sequential number. + **Purpose**: Translate requirements into an *viable solution* — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. **Why It Matters**: @@ -62,6 +64,7 @@ This document defines the documentation framework for a software project. It est - Provides a reference for evaluating specification choices against intended solution **Content Guidelines**: +- Document ID: Include the solution design document ID at the top (e.g., `SD-001`) - Problem decomposition: Break down the user problem into smaller, solvable pieces - Solution approach: Describe the high-level approach (e.g., "Use event sourcing for audit trail", "Implement caching layer for performance") - Alternatives considered: Document at least 2-3 alternative approaches with rationale for why they were rejected @@ -69,7 +72,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 +- Solution Design IDs: Assign unique IDs to major decisions (e.g., `SD-2.1` 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 @@ -494,6 +497,8 @@ Break down the user problem into smaller, solvable pieces. |---------|-------------|-------------| | [Problem ID] | Brief description of the problem | How this affects the user | +**Solution Design ID**: SD-001 + **Example**: - **P-001**: Users cannot compare multiple wines side-by-side → They must navigate between wine pages, losing context and making comparisons difficult