diff --git a/ASG_Framework.md b/ASG_Framework.md index a6f56d5..d142a2b 100644 --- a/ASG_Framework.md +++ b/ASG_Framework.md @@ -9,9 +9,9 @@ This document defines the documentation framework for a software project. It est | Document | Purpose | Primary Audience | Format / Content | Example (SaaS Context) | Measurement (KPI) | |----------|---------|-----------------|------------------|------------------------|-------------------| | **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)." | 0 solution components without a requirement ID reference. | -| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion for each participant. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers, End Users | Per-participant sections, sequence diagrams, state machine diagrams. Explicitly links to solution-design.md and requirements.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. | -| **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). | +| **Solution Design** | Translate requirements into **a 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, decision rationale, high-level component diagram, alternatives considered. | "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)." | 0 solution components without a requirement ID reference. | +| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion for each participant. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers, End Users | Per-participant sections, sequence diagrams, state machine diagrams. Explicitly links to `2-solution_design.md` and `1-requirements.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. | +| **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-001.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). | | **Validation** | The **enforcer** — defines tests before implementation begins to ensure spec compliance. Blocks drift and human error. | QA Engineers, Developers, Automation servers | Unit tests, integration tests, performance tests, penetration tests, contract tests, CI jobs, linting rules, schema validation. | CI job rejects PR with camelCase field not allowed by YAML spec. | <1% of PRs bypass validation gates. | | **Implementation Plan** | The **execution roadmap** — how implementation is organized, prioritized, and delivered. Maps code to validation tests and 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 validation tests covered by implementation tasks, <10% timeline drift. | @@ -42,7 +42,7 @@ This document defines the documentation framework for a software project. It est - 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. +- 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. Walkthrough steps (WT-XXX) may also cite requirement IDs directly. **Best Practices**: - **Link each requirement to a measurable KPI** — functional requirements should have explicit KPIs; non-functional requirements should have measurable thresholds @@ -55,7 +55,7 @@ This document defines the documentation framework for a software project. It est ### 2. Solution Design `2-solution_design.md` -**Purpose**: Translate requirements into an *viable solution* — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. +**Purpose**: Translate requirements into **a viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. **Why It Matters**: - Prevents technical-first thinking that skips design decisions @@ -66,10 +66,10 @@ This document defines the documentation framework for a software project. It est **Content Guidelines**: - 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 +- Solution approach: Introduce the solution the way Steve Jobs introduced the iPhone — present what you're delivering to the user first, then explain how it solves their problem. The narrative starts with the product, not the technical components. (e.g., "We're building a comparison table that lets users evaluate wines side-by-side with instant filtering and sorting" — not "We'll use event sourcing with a caching layer") +- Decision rationale: Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem. (e.g., "We chose server-side rendering so shared comparisons are indexable by search engines, enabling retailers to distribute links without login walls") - High-level component diagram: Show major components and their relationships (not technical details, just the big picture) -- Decision rationale: Explain why each major decision was made (e.g., "Chose NATS over Kafka for simpler ops", "Used server-side rendering for SEO") +- Alternatives considered: Document at least 2-3 alternative approaches with rationale for why they were rejected - 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 - Decision IDs: Assign unique IDs to major decisions using the format `SD-XXX` (e.g., `SD-001` for "Use NATS for async messaging") to enable specification traceability @@ -80,7 +80,7 @@ This document defines the documentation framework for a software project. It est - Use diagrams that are easy to update (Mermaid.js) - Document trade-off decisions explicitly - Review solution design against requirements to verify completeness -- Get sign-off from product, architecture, and engineering before creating walkthroughs +- Create walkthroughs to validate the solution design end-to-end; sign-off from product, architecture, and engineering happens after walkthroughs confirm the approach works **Gap-Check Question**: Does the Solution Design clearly explain how the system solves the user problem, not just what it does? @@ -89,20 +89,12 @@ This document defines the documentation framework for a software project. It est --- ### 3. Walkthrough -`3-walkthrough.md` +`3-walkthrough.md` (single file with per-participant sections) **Primary Audience**: Product Owners, Architects, Developers, End Users **Purpose**: The *end-to-end trace* — each section maps one system participant's complete journey from their own POV, from session start to task completion. Provides a "big picture" view that validates solution design before technical specification is locked. Each section is standalone: described entirely from that participant's perspective, with cross-references to other participants' sections where their workflows intersect. -**System Participants Overview** - -| Participant | Section | Role | What It Shows | -|-------------|---------|------|---------------| -| **[Participant A Name]** | Participant A | [Brief role description] | [Key end-to-end journey summary] | -| **[Participant B Name]** | Participant B | [Brief role description] | [Key end-to-end journey summary] | -| **[Participant C Name]** | Participant C | [Brief role description] | [Key end-to-end journey summary] | - **Per-Participant Walkthroughs** The walkthrough is organized as one document with a dedicated section per system participant, each tracing the complete journey from that participant's perspective. - Traces the complete flow from that participant's login/session start to task completion and logout @@ -127,12 +119,13 @@ The walkthrough is organized as one document with a dedicated section per system - Error paths and edge cases specific to that participant's journey - Sequence diagrams showing request/response patterns across participants for complex multi-user flows - State machine diagrams for workflows that span multiple participants -- Each major walkthrough step must cite the exact **Solution Design decision ID(s)** (e.g., SD-001, SD-002) from `solution-design.md` and/or **Requirement ID(s)** from `requirements.md` that it implements or depends on. +- Each major walkthrough step must cite the exact **Solution Design decision ID(s)** (e.g., SD-001, SD-002) from `2-solution_design.md` and/or **Requirement ID(s)** from `1-requirements.md` that it implements or depends on. +- Assign a unique ID to each walkthrough step using the format `WT-XXX` (e.g., `WT-001` for Participant A login, `WT-002` for Participant B order placement) to enable downstream traceability **Best Practices**: - Write each section from one participant's perspective, then cross-reference other participants' sections - Include concrete examples with realistic data values for each participant's typical usage -- Link each step to its corresponding Solution Design decision (SD-XXX IDs) and requirement IDs +- Link each step to its corresponding Solution Design decision (SD-XXX.Y IDs), Requirement ID(s), and Walkthrough ID (WT-XXX) - Map cross-participant interactions explicitly (e.g., "Customer action X → Retailer notification Y") - Document failure modes and recovery paths from each participant's perspective - Keep walkthroughs updated as requirements and participant roles evolve @@ -142,6 +135,7 @@ The walkthrough is organized as one document with a dedicated section per system ### 4. Specification `4-specification.md` + **Purpose**: 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). **Why It Matters**: @@ -157,10 +151,11 @@ The walkthrough is organized as one document with a dedicated section per system - Error codes and their meanings - Data validation rules and constraints - Rate limiting and quota definitions +- Assign a unique ID to each specification item using the format `SP-XXX` (e.g., `SP-001` for the Request schema, `SP-002` for POST endpoint) for downstream traceability - 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. + - **Requirement ID(s)** from `1-requirements.md` (e.g., FR-001, NFR-201) — defines *what* the system must do + - **Solution Design reference(s)** from `2-solution_design.md` (e.g., SD-001.1, SD-002.1) — 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 it implements or satisfies. **Best Practices**: - Use formal specification languages (OpenAPI 3.0+, AsyncAPI) @@ -190,7 +185,8 @@ The walkthrough is organized as one document with a dedicated section per system - Design tokens (CSS variables, Figma tokens) - Accessibility standards (WCAG compliance) - Responsive design breakpoints and layouts -- Each UI specification artifact must cite the specific requirement ID(s) from requirements.md (for example FR-001, NFR-201) and/or the exact specification ID(s) or spec path(s) from specification.md that it implements or depends on. +- Each UI specification artifact must cite the specific requirement ID(s) from `1-requirements.md` and/or the exact solution design decision ID(s) from `2-solution_design.md` that it implements or depends on +- Assign a unique ID to each UI artifact using the format `UI-XXX` (e.g., `UI-001` for Login Form, `UI-002` for Wine Table) to enable downstream traceability **Best Practices**: - Use design systems with versioned component libraries @@ -217,7 +213,7 @@ Because implementation must satisfy specifications, Validation derives all test | **4. Specification** | API contracts, data schemas, error codes, validation rules | | **5. UI Specification** | Component states, visual patterns, accessibility compliance | -Every specification rule, walkthrough journey, and NFR threshold must have a corresponding test. Tests are written before code so implementation can be validated as it's built. If a spec rule, walkthrough journey, or NFR has no corresponding test, the Validation doc is incomplete. +Every specification rule, walkthrough journey, and NFR threshold must have a corresponding test — each spec item carries an `SP-XXX` ID, every walkthrough step carries a `WT-XXX` ID, and every UI artifact carries a `UI-XXX` ID. Tests are written before code so implementation can be validated as it's built. If a spec rule, walkthrough journey, NFR threshold, or UI state has no corresponding test, the Validation doc is incomplete. **Test Types** @@ -225,40 +221,44 @@ Each validation test must include explicit references to its source document: | Test Type | Source | Example Reference | |-----------|--------|-------------------| -| **Unit tests** | specification.md, ui-specification.md | `specification.md:3.2.1` rejects camelCase headers; `ui-specification.md:## Wine Table` sort states | -| **Integration tests** | 3-walkthrough.md, specification.md | Participant A section step 4.2 → endpoint chain in specification.md | -| **Performance tests** | requirements.md NFRs, solution-design.md | `NFR-101` latency threshold; `SD-002` WebSocket performance decision | -| **Penetration tests** | requirements.md security NFRs, specification.md auth endpoints | `NFR-301` authentication; `specification.md:auth/login` endpoint | -| **Contract tests** | specification.md sections | Mapped to endpoint definitions and schema constraints | -| **Linting rules** | ui-specification.md style guides | Enforcing design tokens from ui-specification.md | -| **Schema validation** | specification.md data schemas | Validating Arrow stream headers (snake_case), JSON payloads | -| **Visual regression** | ui-specification.md component states | Verifying hover, disabled, error states match spec | -| **Security scanning** | requirements.md, specification.md | SAST, dependency vulnerability checks, OWASP rules | +| **Unit tests** | `4-specification.md`, `5-ui_specification.md` | `4-specification.md:3.2.1` rejects camelCase headers; `5-ui_specification.md:## Wine Table` sort states | +| **Integration tests** | `3-walkthrough.md`, `4-specification.md` | `WT-001` Participant A login → endpoint chain in `4-specification.md`; `SP-002` | +| **Performance tests** | `1-requirements.md` NFRs, `2-solution_design.md` | `NFR-101` latency threshold; `SD-002` WebSocket performance decision | +| **Penetration tests** | `1-requirements.md` security NFRs, `4-specification.md` auth endpoints | `NFR-301` authentication; `4-specification.md:auth/login` endpoint | +| **Contract tests** | `4-specification.md` sections | Mapped to endpoint definitions and schema constraints | +| **Linting rules** | `5-ui_specification.md` style guides | Enforcing design tokens from `5-ui_specification.md` | +| **Schema validation** | `4-specification.md` data schemas | Validating Arrow stream headers (snake_case), JSON payloads | +| **Visual regression** | `5-ui_specification.md` component states | Verifying hover, disabled, error states match spec | +| **Security scanning** | `1-requirements.md`, `4-specification.md` | SAST, dependency vulnerability checks, OWASP rules | | **CI/CD pipeline** | All test types above | Automated execution on every commit and PR | **Specification-to-Test Execution Trace** -Every specification rule must have a runnable, verifiable test. This trace maps each spec item to its corresponding test file, test function, and CI gate — proving that every requirement was tested, not just claimed. +Every traceable item — specification rules (SP-XXX), walkthrough journeys (WT-XXX), UI artifacts (UI-XXX), NFR thresholds, and SD decisions — must have a runnable, verifiable test. This trace maps each item to its corresponding test file, test function, and CI gate — proving that every requirement was tested, not just claimed. **Trace Format**: -| Requirement ID | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status | -|----------------|-------------|----------------|-------------------|------------------------|---------|--------| -| FR-001 | `specification.md#/components/schemas/Request` | `tests/unit/schema-validation.test.ts` | `test_rejects_camelCase_headers` | — | `ci/contract-validation.yaml` | Pass | -| FR-002 | `specification.md#/paths/~1api~1v1~1endpoint` | `tests/unit/api-routes.test.ts` | `test_post_wine_returns_201` | `tests/integration/wine-flow.test.ts` | `ci/contract-validation.yaml` | Pass | -| FR-003 | `specification.md#/paths/~1api~1v1~1endpoint` | — | — | `tests/integration/error-handling.test.ts` | `ci/contract-validation.yaml` | Pass | -| NFR-101 | `requirements.md:4.1` | — | — | `tests/performance/load.test.ts` | `ci/performance.yaml` | Pass | -| SD-001 | `solution-design.md:5.1` | — | — | `tests/integration/nats-async.test.ts` | `ci/integration.yaml` | Pass | -| UI-WineTable | `ui-specification.md## Wine Table` | `tests/unit/wine-table.test.tsx` | `test_sort_by_name` | `tests/visual/wine-table.spec.js` | `ci/visual-regression.yaml` | Pass | +| Requirement/Spec ID | Participant | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status | +|---------------------|-------------|-------------|----------------|-------------------|------------------------|---------|--------| +| SP-001 | — | `4-specification.md#/components/schemas/Request` | `tests/unit/schema-validation.test.ts` | `test_rejects_camelCase_headers` | — | `ci/contract-validation.yaml` | Pass | +| SP-002 | — | `4-specification.md#/paths/~1api~1v1~1endpoint` | `tests/unit/api-routes.test.ts` | `test_post_wine_returns_201` | `tests/integration/wine-flow.test.ts` | `ci/contract-validation.yaml` | Pass | +| WT-001 | Customer | `3-walkthrough.md:#login` | `tests/integration/customer-login.test.ts` | `test_login_flow` | — | `ci/integration.yaml` | Pass | +| WT-002 | Retailer | `3-walkthrough.md:#order` | `tests/integration/retailer-order.test.ts` | `test_order_placement` | — | `ci/integration.yaml` | Pass | +| NFR-101 | — | `1-requirements.md:4.1` | — | — | `tests/performance/load.test.ts` | `ci/performance.yaml` | Pass | +| SD-001 | — | `2-solution_design.md:5.1` | — | — | `tests/integration/nats-async.test.ts` | `ci/integration.yaml` | Pass | +| UI-001 | — | `5-ui_specification.md## Wine Table` | `tests/unit/wine-table.test.tsx` | `test_sort_by_name` | `tests/visual/wine-table.spec.js` | `ci/visual-regression.yaml` | Pass | -**Additional Test File(s)** column covers: integration tests (participant section flows), performance tests (NFR benchmarks), penetration tests (security NFRs), and visual regression tests (UI component states). +**Additional Test File(s)** column covers: unit tests (spec rules, UI states), integration tests (WT walkthrough flows), performance tests (NFR benchmarks), penetration tests (security NFRs), contract tests (endpoint/schema pairs), linting rules (design tokens), schema validation (data schemas), security scanning (SAST/dependency checks), and visual regression tests (UI component states). **Trace Rules**: -- **Every** specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test -- **Every** participant section journey must have at least one integration test +- **Every** specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test and one contract test — each spec item carries an `SP-XXX` ID +- **Every** walkthrough journey must have at least one integration test — each walkthrough step carries a `WT-XXX` ID - **Every** performance NFR must have at least one performance test (load/stress/benchmark) - **Every** security NFR must have at least one penetration test scenario -- **Every** UI component state must have at least one unit test (behavior) and one visual regression test (appearance) +- **Every** UI component state must have at least one unit test (behavior) and one visual regression test (appearance) — each UI artifact carries a `UI-XXX` ID +- **Every** data schema must have at least one schema validation test +- **Every** style guide token must have at least one linting rule +- **Every** security NFR must have at least one security scanning test (SAST/dependency checks) - A test may cover multiple spec items, but each spec item must be covered by **at least one** test - Status is tracked via CI gate results (Pass/Fail/Skipped) — not manual checks @@ -271,10 +271,10 @@ Every specification rule must have a runnable, verifiable test. This trace maps - Document validation failure remediation steps **How to Maintain**: -1. When writing a new spec rule, add a trace row **before** implementation +1. When writing a new spec rule, assign an SP-XXX ID; when writing walkthrough steps assign WT-XXX; when defining UI artifacts assign UI-XXX; when creating implementation tasks assign IMP-XXX — then add trace rows **before** implementation 2. When writing the test, fill in the test file and function 3. CI gate auto-updates Status from pipeline results -4. Gap-Check step 6 (Validation Review) verifies 100% row coverage — no spec rule without a test +4. **Gap-Check Step 5** (Validation Review) verifies 100% row coverage — no traceable item without a test **Tooling** (optional): - Use YAML or JSON files (e.g., `validation/test-trace.yaml`) as machine-readable trace data @@ -296,14 +296,14 @@ Every specification rule must have a runnable, verifiable test. This trace maps **Content Guidelines**: - Implementation phases and timeline (e.g., Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation) - Module/component breakdown with responsibilities and dependencies -- Task list with assignees, priorities, and estimated effort -- Test coverage: which validation tests each implementation task satisfies +- Task list with assignees, priorities, estimated effort — assign unique task IDs using the format `IMP-XXX` (e.g., `IMP-001` for Core API implementation) +- Test coverage: which validation tests each IMP-XXX task satisfies - Build and deployment preparation (CI/CD setup, environment configuration) - Risk mitigation: known blockers and mitigation steps **Best Practices**: -- Break implementation into small, testable increments (1-3 day sprints) -- Map each implementation task to specific validation tests (not just specification sections) +- Break implementation into small, testable increments (1-3 day task units) +- Assign an `IMP-XXX` ID to each implementation task and map it to specific validation tests it satisfies - Define clear ownership for each module or component - Include test coverage targets for each phase - Document dependencies between modules to avoid blocking work @@ -329,8 +329,8 @@ Every specification rule must have a runnable, verifiable test. This trace maps - Troubleshooting guides for common issues - Runbook entries for specific error codes - Contact information and escalation paths -- Explicit references to [`specification.md`](specification.md) (API contracts, data schemas, specific endpoint sections) -- Explicit references to [`ui-specification.md`](ui-specification.md) (components, interactions, visual states, specific component sections) +- Explicit references to [`4-specification.md`](4-specification.md) (API contracts, data schemas, specific endpoint sections) +- Explicit references to [`5-ui_specification.md`](5-ui_specification.md) (components, interactions, visual states, specific component sections) **Best Practices**: - Write runbooks for every P1/P2 incident @@ -354,15 +354,15 @@ Before writing any code or documentation, establish clear requirements. Ask: ### 2. Define Solution Design -Once requirements are stable, translate them into an viable solution. This ensures the technical approach solves the user problem, not just requirements. +Once requirements are stable, translate them into a viable solution. This ensures the technical approach solves the user problem, not just requirements. -**Action**: Create `docs/solution-design/` with `solution-design.md`, problem decomposition, alternatives considered, high-level component diagram, and decision rationale. +**Action**: Create `docs/solution-design/` with `2-solution_design.md`, problem decomposition, solution approach, decision rationale, high-level component diagram, and alternatives considered. ### 3. Create Walkthroughs Early -As soon as the solution design is defined, create walkthroughs — one document with a section per system participant. This helps identify gaps in each participant's flow and provides onboarding material. Each section traces the complete journey from that participant's perspective and cross-references other participants' workflows. The walkthrough should explicitly link to solution-design.md (SD-XXX IDs) and requirements.md. +As soon as the solution design is defined, create walkthroughs — one document with a section per system participant. This helps identify gaps in each participant's flow and provides onboarding material. Each section traces the complete journey from that participant's perspective and cross-references other participants' workflows. The walkthrough should explicitly link to `2-solution_design.md` (SD-XXX.Y IDs) and `1-requirements.md`. -**Action**: Create `docs/walkthrough/` with `3-walkthrough.md` containing one section per participant (e.g., Customer, Retailer, Admin), sequence diagrams, and cross-references to solution design decisions and requirements. +**Action**: Create `docs/walkthrough/` with `3-walkthrough.md` containing one section per participant (e.g., Customer, Retailer, Admin), sequence diagrams, and cross-references to `2-solution_design.md` (SD-XXX.Y IDs) and `1-requirements.md`. ### 4. Define the Specification @@ -370,25 +370,25 @@ With walkthrough in place, define the technical specification. This becomes the - **Requirements** (WHAT - business intent) - **Solution Design** (HOW/WHY - architectural decisions) -**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to requirements.md, solution-design.md, and 3-walkthrough.md. +**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to `1-requirements.md`, `2-solution_design.md`, and `3-walkthrough.md`. Each specification item must have an `SP-XXX` ID. ### 5. Define UI Specification Early Create UI specifications before implementing frontend components. This ensures design consistency and provides a contract for implementation. -**Action**: Create `docs/ui-specification/` with `component-library.md`, `style-guide.md`, and `design-tokens.json`. +**Action**: Create `docs/ui-specification/` with `component-library.md`, `style-guide.md`, and `design-tokens.json`. Each UI artifact must have a `UI-XXX` ID. ### 6. Define Validation Tests Before Implementation -Write validation tests **before** implementation begins. This ensures every specification rule and UI state has a corresponding test that defines success. Tests should reference specification.md, ui-specification.md, requirements.md (NFR thresholds), and solution-design.md (performance decisions). Create a specification-to-test execution trace that maps every spec item to its test file, test function, and CI gate. +Write validation tests **before** implementation begins. This ensures every specification rule (SP-XXX), walkthrough journey (WT-XXX), UI state (UI-XXX), and NFR threshold has a corresponding test that defines success. Tests should reference `4-specification.md`, `5-ui_specification.md`, `3-walkthrough.md`, `1-requirements.md` (NFR thresholds), and `2-solution_design.md` (performance decisions). Create a specification-to-test execution trace that maps every spec item to its test file, test function, and CI gate. -**Action**: Create `docs/validation/` with `unit-tests/` (spec rules, schema fields, component states), `integration-tests/` (end-to-end flows from each participant walkthrough section), `performance-tests/` (NFR benchmarks: latency, TPS), `penetration-tests/` (security NFRs, auth flows), `contract-tests/`, `ci-pipeline.yaml`, `lint-rules/`, and `test-trace.yaml` (specification-to-test execution trace mapping every spec path to its test file, test function, and CI gate). +**Action**: Create `docs/validation/` with `unit-tests/` (spec rules, schema fields, component states), `integration-tests/` (WT-XXX walkthrough flows), `performance-tests/` (NFR benchmarks: latency, TPS), `penetration-tests/` (security NFRs, auth flows), `contract-tests/`, `ci-pipeline.yaml`, `lint-rules/`, and `test-trace.yaml` (specification-to-test execution trace mapping every spec path to its test file, test function, and CI gate). ### 7. Create Implementation Plan -With validation tests defined, create the implementation plan. Map each implementation task to specific validation tests that it must satisfy. +With validation tests defined, create the implementation plan. Assign `IMP-XXX` IDs to each task and map them to the specific validation tests they must satisfy. -**Action**: Create `docs/implementation-plan/` with phases, module breakdown, task list with assignees, and test coverage targets. +**Action**: Create `docs/implementation-plan/` with `7-implementation-plan.md` containing phases, module breakdown, task list with assignees/priorities/effort (`IMP-XXX` IDs), and test coverage targets. ### 8. Document Operations from Day One @@ -405,11 +405,11 @@ Since all docs defined in the ASG Framework are **living documents** that evolve | Stage Transition | Goal | Gap-Check Question | Example Gap | Result | |------------------|------|-------------------|-------------|--------| | **Requirements → Solution Design** | Turn a "Wish" into a "Solution" | Does the Solution Design clearly explain how the system solves the user problem, not just what it does? | Requirements say "users can compare wines", but solution design only mentions "wine comparison API" without explaining how users will actually use the comparison feature | Add UI flow and user interaction patterns to the solution design | -| **Solution Design → Walkthrough** | Turn a "Solution" into a "Story" | Does every participant section trace the complete flow the Solution Design describes, including all SD-XXX decisions? Is there a section for each system participant? | Solution design says "use NATS for async messaging", but Participant A section doesn't trace the async flow or reference SD-001 | Add the async messaging flow with SD-001 reference to Participant A section | -| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does the Specification cover all the behaviors defined in every participant section? | Participant A section shows 10 interaction steps, but Specification only defines 2 REST endpoints | Add the missing endpoint definitions to Specification | -| **Specification → UI Specification** | Turn a "Rule" into a "Button" | Does the UI Specification expose all the data and states defined in the Specification? | Specification says device must "Handshake" within 5 seconds, but UI Specification has no connection status indicator | Add a `Connection Status` component to UI Specification | +| **Solution Design → Walkthrough** | Turn a "Solution" into a "Story" | Does every SD-XXX decision appear in at least one participant's walkthrough section? Is there a WT-XXX ID for every walkthrough step? Is there a section for each system participant? | Solution design defines SD-001 (NATS async messaging), but no participant section traces the async flow | Add an async messaging flow to Participant B section with SD-001 reference and WT-003 ID | +| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does the Specification define SP-XXX rules for every WT-XXX walkthrough step? | Walkthrough defines 20 WT-XXX steps across 3 participants, but Specification only has SP-001 through SP-005 (10 items) | Add the missing endpoint definitions, schema rules, and error codes to Specification with SP-006 through SP-020 | +| **Specification → UI Specification** | Turn a "Rule" into a "Button" | Does the UI Specification expose all data entities and states defined in the Specification? Are UI-XXX IDs assigned to every UI artifact? | Specification defines 15 API response schemas with 30 fields, but UI Specification only has 3 components (UI-001 through UI-003) | Add the remaining UI components for each data entity with UI-XXX IDs to match Specification coverage | **UI Specification → Validation** | Turn "Design" into "Tests" | Do the Validation tests cover all specification rules, UI states, performance NFRs, and security requirements? | UI Spec defines 15 component states but Validation only has 5 unit tests; NFR-101 latency threshold has no performance test | Add unit tests for all component states, performance benchmarks for NFR thresholds, and pen test scenarios for security NFRs | -| **Validation → Implementation Plan** | Turn "Tests" into "Tasks" | Does the Implementation Plan satisfy all validation tests with clear ownership? | Validation defines 30 test cases but Implementation Plan only has tasks for 20 | Add implementation tasks for remaining test cases with assignees and timelines | +| **Validation → Implementation Plan** | Turn "Tests" into "Tasks" | Does the Implementation Plan satisfy all validation tests with clear ownership? | Validation defines 30 test cases but Implementation Plan only has tasks for 20 | Verify every validation test maps to at least one implementation task with an assignee and timeline | ### Why Gap-Checks Matter @@ -422,13 +422,14 @@ 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. **Walkthrough Review**: After writing walkthrough, verify every SD-XXX decision and requirement is traced in every participant section with error paths included, and that each system participant has a dedicated section +3. **Walkthrough Review**: After writing walkthrough, verify every SD-XXX.Y decision, requirement ID, and WT-XXX walkthrough step is traced in every participant section with error paths included, and that each system participant has a dedicated section 4. **Specification Review**: After writing the spec, verify every spec item has: + - An `SP-XXX` ID assigned for downstream traceability - At least one requirement ID reference (WHAT) - At least one solution design reference (HOW/WHY) - Coverage for all behaviors defined in each participant section -5. **UI Specification Review**: After writing UI Specification, verify every spec rule has at least one UI representation with a corresponding requirement ID reference -6. **Validation Review**: After writing Validation, verify every specification section and UI state has at least one corresponding unit/integration test case; every performance NFR has a benchmark test; every security NFR has a penetration test scenario — each with explicit references to specification.md, ui-specification.md, and/or requirements.md +5. **UI Specification Review**: After writing UI Specification, verify every `UI-XXX` artifact has a corresponding requirement ID, solution design reference, and specification ID +6. **Validation Review**: After writing Validation, verify every specification section and UI state has at least one corresponding test case — unit tests for SP-XXX spec rules and UI-XXX UI states, integration tests for WT-XXX walkthrough flows, performance tests for NFR thresholds, penetration test scenarios for security NFRs, contract tests for SP-XXX endpoint/schema definitions, linting rule coverage for `5-ui_specification.md` style guides, schema validation for all data schemas, and security scanning for all security NFRs — each with explicit references to `4-specification.md`, `5-ui_specification.md`, `3-walkthrough.md`, and/or `1-requirements.md` 7. **Implementation Plan Review**: After writing the plan, verify every validation test is covered by at least one implementation task with an assignee and timeline --- @@ -440,11 +441,11 @@ This habit ensures that each documentation stage is complete and validated befor | Stage | Debug Checklist | Why It Matters | |-------|-----------------|----------------| | **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 | -| **Walkthrough** | If I can't Trace every participant's full flow, the system has 'broken bridges'. | Identifies gaps between components and validates the solution design end-to-end for each system participant | -| **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 | -| **Validation** | If I can't Write a Test for every spec rule, UI state, NFR threshold, and security requirement, implementation is untestable. | Ensures code can be tested from day one — unit, integration, performance, and pen tests define success before implementation begins | +| **Solution Design** | If I can't see the Solution, I'm building without a compass. | Ensures the technical approach solves the user problem before spec writing | +| **Walkthrough** | If I can't Trace every participant's flow with **WT-XXX** IDs, the system has broken bridges. | Identifies gaps between components and validates the solution design end-to-end for each system participant | +| **Specification** | If I can't write a Rule with a requirement and 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 **UI-XXX** ID and traceability reference, the user has no way to trigger the logic. | Ensures traceability from UI elements to business requirements | +| **Validation** | If I can't Write a Test for every traceable item, implementation is untestable. | Ensures code can be tested from day one — unit, integration, performance, contract, and security tests define success before implementation begins | **How to Use This Habit:** @@ -478,11 +479,11 @@ Each documentation artifact has associated KPIs. Track these to ensure quality: |----------|-----|--------| | Requirements | Requirement coverage | 100% of features have associated requirements | | Solution Design | Solution completeness | 0 solution components without a requirement ID reference | +| Walkthrough | Participant coverage | 100% of identified system participants have a walkthrough section | | Specification | Specification compliance rate | 100% of messages validate against spec | | UI Specification | UI spec compliance | 100% of components match design spec (visual regression tests) | -| Walkthrough | New dev time-to-first-PR | <2 days from onboarding to first contribution | -| Implementation | Test coverage | >80% unit test coverage | | Validation | Bypass rate | <1% of PRs bypass validation gates | +| Implementation | Test coverage | >80% unit test coverage | | Runbook | MTTR | <15 minutes for P1 incidents | **Review Cadence**: @@ -594,14 +595,18 @@ These rules serve as a binary decision framework: ## 6. Requirements Traceability Matrix -| Requirement ID | Description | Implementation File | Test File | -|----------------|-------------|---------------------|-----------| -| FR-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` | -| NFR-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` | +| Requirement ID | WT ID | SP ID | UI ID | IMP ID | Description | Implementation File | Test File | +|----------------|-------|-------|-------|--------|-------------|---------------------|-----------| +| FR-XXX | WT-XXX | SP-XXX | UI-XXX | IMP-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` | +| NFR-XXX | WT-XXX | SP-XXX | UI-XXX | IMP-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` | **Notes**: - Functional Requirements (FR) define what the system shall do - Non-Functional Requirements (NFR) define system qualities (performance, availability, security, etc.) +- **WT-XXX** IDs link requirements to walkthrough journey steps in `3-walkthrough.md` +- **SP-XXX** IDs are assigned to each specification item in `4-specification.md` for downstream traceability (Validation, Implementation Plan) +- **UI-XXX** IDs are assigned to each UI artifact in `5-ui_specification.md` for downstream traceability (Validation, Implementation Plan) +- **IMP-XXX** IDs are assigned to each implementation task in `7-implementation-plan.md` for downstream mapping to validation tests - KPIs are measurable targets that validate whether requirements were met post-deployment - Each requirement must include a clear requirement ID for traceability - All acceptance conditions must be verifiable through testing or manual inspection @@ -634,15 +639,17 @@ Describe the high-level approach to solving the problem. - [e.g., "Use server-side rendering for SEO"] - [e.g., "Support unlimited wine comparisons for power users"] -## 3. Alternatives Considered +## 3. Decision Rationale -Document at least 2-3 alternative approaches with rationale. +Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem. -| Alternative | Pros | Cons | Decision | -|-------------|------|------|----------| -| Client-side comparison | Fast updates, no server load | Memory-intensive, no sharing | Rejected - memory constraints on mobile | -| Server-side comparison | Centralized, scalable | Latency, complex state sync | Accepted - matches performance requirements | -| Hybrid approach | Best of both worlds | Complex, hard to maintain | Rejected - over-engineering | +| Decision ID | Decision | Rationale | Alternatives Rejected | +|-------------|----------|-----------|----------------------| +| SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale | +| SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests | +| SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature | +| SD-004 | Server-side rendering for comparison view | SEO for comparison pages shared via unique links | Client-side rendering - no SEO benefit | +| SD-005 | Server-side PDF/CSV export | Generates downloadable exports with user data | Client-side export — requires user browser permissions | ## 4. High-Level Component Diagram @@ -659,16 +666,15 @@ flowchart TD - **[Component Name]**: [Brief description of responsibilities and how it solves part of the problem] - Links to requirements: FR-001, NFR-201 -## 5. Decision Rationale +## 5. Alternatives Considered -Explain why each major decision was made. +Document at least 2-3 alternative approaches with rationale. -| Decision ID | Decision | Rationale | Alternatives Rejected | -|-------------|----------|-----------|----------------------| -| SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale | -| SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests | -| SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature | -| SD-004 | Server-side rendering for comparison export | SEO for shared comparisons | Client-side rendering - no SEO benefit | +| Alternative | Pros | Cons | Decision | +|-------------|------|------|----------| +| Client-side comparison | Fast updates, no server load | Memory-intensive, no sharing | Rejected - memory constraints on mobile | +| Server-side comparison | Centralized, scalable | Latency, complex state sync | Accepted - matches performance requirements | +| Hybrid approach | Best of both worlds | Complex, hard to maintain | Rejected - over-engineering | ## 6. Risk Assessment @@ -687,10 +693,10 @@ Link each solution component to specific requirements and assign Solution Design | Solution Component | Requirement ID | Decision ID | Description | |-------------------|----------------|-------------|-------------| | Comparison table UI | FR-101 | SD-001 | Display wines in table format (uses NATS messaging) | -| Filtering | FR-102 | SD-002 | Filter wines by criteria (uses WebSocket updates) | -| Sorting | FR-103 | SD-003 | Sort wines by any column (stored in localStorage) | +| Filtering | FR-102 | SD-003 | Filter wines by criteria (stored in localStorage) | +| Sorting | FR-103 | SD-004 | Sort wines by any column (stored in localStorage) | | Real-time updates | NFR-201 | SD-002 | Updates appear within 100ms (uses WebSocket) | -| Export comparison | FR-201 | SD-004 | Export comparison to PDF/CSV (uses server-side rendering) | +| Export comparison | FR-201 | SD-005 | Export comparison to PDF/CSV (uses server-side rendering) | ### Specification Template @@ -718,7 +724,8 @@ paths: schema: $ref: '#/components/schemas/Response' x-requirement-id: FR-001 # Reference to Requirements document (WHAT) - x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY) + x-solution-design-ref: SD-001.1 # Reference to Solution Design decision (HOW/WHY) + x-spec-id: SP-001 # Specification item ID for downstream traceability components: schemas: Request: @@ -727,14 +734,16 @@ components: data: type: string x-requirement-id: FR-002 # Reference to Requirements document (WHAT) - x-solution-design-ref: SD-3.2 # Reference to Solution Design decision (HOW/WHY) + x-solution-design-ref: SD-001.2 # Reference to Solution Design decision (HOW/WHY) + x-spec-id: SP-002 # Specification item ID for downstream traceability Response: type: object properties: status: type: string x-requirement-id: FR-003 # Reference to Requirements document (WHAT) - x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY) + x-solution-design-ref: SD-001.1 # Reference to Solution Design decision (HOW/WHY) + x-spec-id: SP-003 # Specification item ID for downstream traceability ``` ### UI Specification Template @@ -746,13 +755,14 @@ components: **Name**: [Component Name] **Status**: [Draft/Approved/Deprecated] **Version**: 1.0.0 +**UI-XXX**: [Unique UI spec ID assigned to this component] ## Requirements Traceability -| 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 | +| UI Element | UI Spec Ref | Requirement ID | Solution Design Ref | Description | +|------------|-------------|----------------|---------------------|-------------| +| Login form | UI-001 | FR-001 | SD-001.1 | Username/password authentication | +| Sidebar menu | UI-002 | FR-102 | SD-002.1 | Collapsible sidebar for navigation | +| Wine table | UI-003 | FR-101 | SD-003.1 | Sortable, searchable inventory table | ## Design Tokens - **Color**: `--color-primary` @@ -760,12 +770,13 @@ components: - **Spacing**: `--spacing-md` ## Component States -| State | Description | Example | Requirement ID | -|-------|-------------|---------|----------------| -| Default | Normal state | `