diff --git a/ASG_Framework.md b/ASG_Framework.md index 995c807..b324ce7 100644 --- a/ASG_Framework.md +++ b/ASG_Framework.md @@ -10,7 +10,7 @@ This document defines the documentation framework for a software project. It est |----------|---------|-----------------|------------------|------------------------|-------------------| | **Requirements** | Capture the **business intent** — why we're building this and what success looks like. Defines boundaries and user-visible outcomes. | Stakeholders, Product Owners, Lead Developers | User stories, PRDs, acceptance criteria, non-functional constraints. | "System must process tabular data from Julia to SvelteKit UI with <200ms latency for 5-member teams." | 95% of requests complete <200ms (synthetic monitoring). | | **Solution Design** | Translate requirements into an **viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. | Product Owners, Architects, Developers | Problem decomposition, solution approach, alternatives considered, high-level component diagram, decision rationale. | "Problem: Users need to compare wines. Solution: Build a comparison table with filtering, sorting, and visual comparison. Components: Data layer (Wine API), UI layer (Table component), Logic layer (Filter/Sort engine)." | 100% of user problems mapped to solution components before spec writing. | -| **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject that accepts Arrow streams with snake_case headers. | 100% of messages validated against spec (CI block rate). | +| **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. Maps technical implementation to both *what* (requirements) and *how* (solution design). | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject (solution-design SD-3.1) that accepts Arrow streams with snake_case headers (requirements FR-001). | 100% of messages validated against spec (CI block rate). | | **UI Specification** | The **design contract** — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation. | Product Designers, Frontend Developers, QA Engineers | Component libraries, style guides, interaction specs, design tokens. | Atomic design system with Figma tokens synced to CSS variables. | 100% of UI components match design spec (visual regression tests). | | **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers | End-to-end user journey, sequence diagrams, state machine diagrams. Explicitly links to specification.md and ui-specification.md. | "User logs in → selects wine → edits details → saves → backend validates against spec → UI updates with error states." | 100% of user journeys traced across all layers before implementation starts. | | **Implementation Plan** | The **execution roadmap** — how implementation is organized, prioritized, and delivered. Maps code to spec and validates against specification. | Developers, Project Managers, Lead Developers | Implementation plan, module breakdown, task list, delivery timeline, test strategy. | Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation. | 100% of specification sections mapped to implementation tasks, <10% timeline drift. | @@ -69,6 +69,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 **Best Practices**: - Write solution design from the user's perspective first, then justify technical choices @@ -101,7 +102,10 @@ This document defines the documentation framework for a software project. It est - Error codes and their meanings - Data validation rules and constraints - Rate limiting and quota definitions -- Each specification item must cite the specific requirement ID(s) from requirements.md (for example, FR-001, NFR-201). Link each endpoint, schema, validation rule, error case, etc to the exact requirement(s) it implements or satisfies. +- Each specification item must cite: + - **Requirement ID(s)** from requirements.md (e.g., FR-001, NFR-201) — defines *what* the system must do + - **Solution Design reference(s)** from solution-design.md (e.g., SD-2.1, SD-3.3) — defines *how* and *why* this technical approach was chosen + - Link each endpoint, schema, validation rule, error case, etc to the exact requirement(s) and solution design decision(s) it implements or satisfies. **Best Practices**: - Use formal specification languages (OpenAPI 3.0+, AsyncAPI) @@ -238,7 +242,11 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio - Integration test suites - Schema validation jobs - Security scanning and audit jobs -- Each validation must include explicit references to requirements.md (e.g., FR-001, NFR-201), specification.md (exact spec IDs or paths — API contracts, data schemas, e.g., sections 3.1, 4.2), and ui-specification.md (components, interactions, visual states, e.g., sections 15.1, 15.3) as applicable. +- Each validation must include explicit references to: + - requirements.md (e.g., FR-001, NFR-201) — business intent + - solution-design.md (e.g., SD-2.1, SD-3.3) — architectural decisions + - specification.md (exact spec IDs or paths — API contracts, data schemas, e.g., sections 3.1, 4.2) — technical rules + - ui-specification.md (components, interactions, visual states, e.g., sections 15.1, 15.3) — UI contract **Best Practices**: - Fail CI on specification violations @@ -298,9 +306,11 @@ Once requirements are stable, translate them into an viable solution. This ensur ### 3. Define the Specification -With solution design in place, define the technical specification. This becomes the contract for implementation. +With solution design in place, define the technical specification. This becomes the contract for implementation. Each specification item must trace to **both**: +- **Requirements** (WHAT - business intent) +- **Solution Design** (HOW/WHY - architectural decisions) -**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format) and `error-codes.md`. +**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to requirements.md and solution-design.md. ### 4. Define UI Specification Early @@ -357,7 +367,9 @@ Since all docs defined in the ASG Framework are **living documents** that evolve 1. **Requirements Review**: After writing requirements, ask "What happens if X?" for each user story 2. **Solution Design Review**: After writing solution design, verify every requirement is addressed by at least one solution component with a corresponding requirement ID reference -3. **Specification Review**: After writing the spec, verify every requirement has at least one rule with a corresponding requirement ID reference +3. **Specification Review**: After writing the spec, verify every spec item has: + - At least one requirement ID reference (WHAT) + - At least one solution design reference (HOW/WHY) 4. **UI Specification Review**: After writing UI Specification, verify every spec rule has at least one UI representation with a corresponding requirement ID reference 5. **Walkthrough Review**: After writing walkthrough, verify every UI step has a corresponding backend flow @@ -371,7 +383,7 @@ This habit ensures that each documentation stage is complete and validated befor |-------|-----------------|----------------| | **Requirements** | If I can't state the Value, I'm building a feature nobody needs. | Clarifies the business impact before technical discussion begins | | **Solution Design** | If I can't Imagine the solution, I'm building without a compass. | Ensures the technical approach solves the user problem before spec writing | -| **Specification** | If I can't write a Rule with a requirement ID reference, I haven't thought the logic through. | Ensures traceability from technical rules to business requirements | +| **Specification** | If I can't write a Rule with a requirement ID reference AND/OR solution design reference, I haven't thought the logic through. | Ensures traceability from technical rules to both business requirements (*what*) and architectural decisions (*how/why*) | | **UI Specification** | If I can't See it with a requirement ID reference, the user has no way to trigger the logic. | Ensures traceability from UI elements to business requirements | | **Walkthrough** | If I can't Trace the full flow, the system has a 'broken bridge'. | Identifies gaps between components before implementation begins | @@ -543,15 +555,15 @@ Identify potential risks and mitigation strategies. ## 7. Requirements Traceability -Link each solution component to specific requirements. +Link each solution component to specific requirements and assign Solution Design IDs for specification traceability. -| Solution Component | Requirement ID | Description | -|-------------------|----------------|-------------| -| Comparison table UI | FR-101 | Display wines in table format | -| Filtering | FR-102 | Filter wines by criteria | -| Sorting | FR-103 | Sort wines by any column | -| Real-time updates | NFR-201 | Updates appear within 100ms | -| Export comparison | FR-201 | Export comparison to PDF/CSV | +| 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 | ### Specification Template @@ -562,7 +574,7 @@ openapi: 3.0.0 info: title: NATSBridge API version: 1.0.0 - description: Technical specification with requirements traceability + description: Technical specification with requirements and solution design traceability paths: /api/v1/endpoint: post: @@ -578,7 +590,8 @@ paths: application/json: schema: $ref: '#/components/schemas/Response' - x-requirement-id: FR-001 # Reference to Requirements document + x-requirement-id: FR-001 # Reference to Requirements document (WHAT) + x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY) components: schemas: Request: @@ -586,13 +599,15 @@ components: properties: data: type: string - x-requirement-id: FR-002 # Reference to Requirements document + x-requirement-id: FR-002 # Reference to Requirements document (WHAT) + x-solution-design-ref: SD-3.2 # Reference to Solution Design decision (HOW/WHY) Response: type: object properties: status: type: string - x-requirement-id: FR-003 # Reference to Requirements document + x-requirement-id: FR-003 # Reference to Requirements document (WHAT) + x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY) ``` ### UI Specification Template @@ -606,9 +621,9 @@ components: **Version**: 1.0.0 ## Requirements Traceability -| UI Element | Requirement ID | Description | -|------------|----------------|-------------| -| Login form | FR-001 | Username/password authentication | +| UI Element | Requirement ID | Solution Design Ref | Description | +|------------|----------------|---------------------|-------------| +| Login form | FR-001 | SD-2.1 | Username/password authentication | | Sidebar menu | NFR-202 | Collapsible sidebar for usability | | Wine table | FR-101 | Sortable, searchable inventory table | @@ -657,19 +672,19 @@ flowchart TD ``` **Specification Traceability:** -| Architecture Component | Specification Section | UI Specification Section | Requirement ID | -|------------------------|----------------------|--------------------------|----------------| -| NATS Bridge (smartsend) | specification.md:3.1 | - | FR-301, NFR-201 | -| Login Form | specification.md:10.1 | ui-specification.md:15.2.1 | FR-001, NFR-201 | -| Wine Inventory Table | specification.md:4.2 | ui-specification.md:15.3.3 | FR-101, NFR-205 | -| Sidebar Menu | specification.md:11.1 | ui-specification.md:15.3.2 | NFR-202 | +| Architecture Component | Solution Design Ref | Specification Section | UI Specification Section | Requirement ID | +|------------------------|---------------------|----------------------|--------------------------|----------------| +| NATS Bridge (smartsend) | SD-3.1 | specification.md:3.1 | - | FR-301, NFR-201 | +| Login Form | SD-2.1 | specification.md:10.1 | ui-specification.md:15.2.1 | FR-001, NFR-201 | +| Wine Inventory Table | SD-2.2 | specification.md:4.2 | ui-specification.md:15.3.3 | FR-101, NFR-205 | +| Sidebar Menu | SD-2.3 | specification.md:11.1 | ui-specification.md:15.3.2 | NFR-202 | **Component Details:** -- **Caddy**: Static file serving (specification.md:2.2, ui-specification.md:15.1) -- **Node.js API**: NATS bridge client (specification.md:3.1) -- **Julia Worker**: Backend processing (specification.md:4.1) -- **NATS Cluster**: Message bus (specification.md:3.3) -- **Storage**: Data persistence (specification.md:5.1) +- **Caddy**: Static file serving (specification.md:2.2, ui-specification.md:15.1, solution-design.md:SD-1.1) +- **Node.js API**: NATS bridge client (specification.md:3.1, solution-design.md:SD-3.1) +- **Julia Worker**: Backend processing (specification.md:4.1, solution-design.md:SD-4.1) +- **NATS Cluster**: Message bus (specification.md:3.3, solution-design.md:SD-3.3) +- **Storage**: Data persistence (specification.md:5.1, solution-design.md:SD-5.1) ### Runbook Template