diff --git a/ASG_Framework.md b/ASG_Framework.md index e407518..4552c86 100644 --- a/ASG_Framework.md +++ b/ASG_Framework.md @@ -9,8 +9,8 @@ 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)." | 100% of user problems mapped to solution components before spec writing. | -| **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 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. | +| **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). | | **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. | @@ -22,7 +22,7 @@ This document defines the documentation framework for a software project. It est ## Detailed Document Descriptions ### 1. Requirements -`requirements.md` +`1-requirements.md` **Purpose**: Capture the *business intent* — why we're building this and what success looks like. Defines boundaries and user-visible outcomes. @@ -53,7 +53,7 @@ This document defines the documentation framework for a software project. It est --- ### 2. Solution Design -`solution-design.md` +`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. @@ -89,57 +89,59 @@ This document defines the documentation framework for a software project. It est --- ### 3. Walkthrough -`walkthrough.md` +`3-walkthrough.md` -**Purpose**: The *end-to-end trace* — maps the entire system flow from startup to cycle completion, incorporating both internal logic and external interactions. Provides a "big picture" view that aligns users and developers, validating the solution design before technical specification is locked. +**Primary Audience**: Product Owners, Architects, Developers, End Users -**Unified Lifecycle Review** -The walkthrough functions as a collaborative audit, mapping the proposed solution directly onto your workflow to ensure a shared "single source of truth." It synchronizes the user's operational needs with the developer's technical implementation. +**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. -**For the User: Validating Operational Utility** -- **Visual Fidelity**: Concrete demonstration of the UI and user-facing components -- **Workflow Integration**: Clear mapping of how the tool fits into existing day-to-day operations -- **Operational Control**: Practical exposure to system controls and interaction patterns -- **Outcome Verification**: Direct observation of the system's outputs and deliverables -- **Impact Assessment**: Data-driven evaluation of the solution's ROI and efficiency gains -- **Expectation Alignment**: Early discovery of discrepancies between intended functionality and actual experience +**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: -**For the Developer: Aligning Architecture with Reality** -- **Requirement Validation**: Confirming the solution satisfies core business objectives -- **Impact Analysis**: Assessing the solution's real-world behavioral performance -- **Knowledge Synthesis**: Identifying disconnects between domain intent and technical interpretation -- **Specification Refinement**: Spotting missing technical dependencies or edge cases -- **System Harmony**: Observing how the technical workflow and the user process interleave -- **Code-to-Process Mapping**: Refining abstraction layers to better reflect the user's actual sequence of events +| Walkthrough Section | System Participant | What It Shows | +|---------------------|-------------------|---------------| +| **Participant A Section** | Primary system user (e.g., wine retailer customer) | End-to-end journey: browse → interact → complete task → receive outcome | +| **Participant B Section** | Secondary system user (e.g., wine retailer admin) | End-to-end journey: manage → configure → review → reconcile | +| **Participant C Section** | Tertiary system user (e.g., system administrator) | End-to-end journey: configure → monitor → handle incidents → audit | + +Each section: +- Traces the complete flow from that participant's login/session start to task completion and logout +- Explicitly references steps where other participants' actions are triggered (e.g., "Customer places order → see Retailer section step 4.2") +- Shows error paths, edge cases, and recovery from that participant's perspective +- Uses sequence diagrams to illustrate interactions across participants **Why It Matters**: -- Serves as a single source of truth for system behavior, bridging user experience and technical implementation +- Each section is written entirely from one participant's POV — what they see, do, and achieve +- Each participant sees their complete end-to-end journey in a standalone walkthrough section +- Participants understand how their actions trigger or depend on other participants' workflows - Validates that all components (UI, API, backend logic) work together cohesively before implementation begins -- Exposes solution design gaps and integration risks early in the design phase -- Aligns stakeholders (product, design, development) on the complete user journey +- Exposes solution design gaps and integration risks between participant workflows early in the design phase - Provides a reference for verifying implementation against intended behavior and for tracing requirements through to architecture **Content Guidelines**: -- End-to-end user journey from system startup to task completion +- One section per system participant, starting from their login/session start to task completion +- End-to-end flow: what the participant sees, does, and achieves at each step +- Cross-references to other participants' sections where workflows intersect (e.g., "Customer order placed → see Retailer section step 4.2") - External interactions (user actions, API calls, third-party integrations) -- Internal flow (state transitions, business logic, data transformations) -- Error paths and edge cases with their handling -- Sequence diagrams showing request/response patterns across all layers -- State machine diagrams for complex workflows +- Internal flow (state transitions, business logic, data transformations) triggered by the participant's actions +- 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. **Best Practices**: -- Write walkthroughs from the user's perspective first, then trace the technical implementation -- Include concrete examples with realistic data values +- 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 -- Document failure modes and recovery paths -- Keep walkthroughs updated as requirements evolve -- Review walkthroughs against the solution design to verify completeness +- 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 +- Review walkthroughs against the solution design to verify completeness across all participants --- ### 4. Specification -`specification.md` +`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**: @@ -170,7 +172,7 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio --- ### 5. UI Specification -`ui-specification.md` +`5-ui_specification.md` **Purpose**: The *design contract* — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation. @@ -201,7 +203,7 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio --- ### 6. Validation -`validation.md` +`6-validation.md` **Purpose**: The *enforcer* — defines tests **before implementation begins** to ensure spec compliance. Blocks drift and human error. @@ -217,7 +219,7 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio **Content Guidelines**: - **Unit tests** — atomic tests for each specification rule, data schema field, and UI component state (cites specification.md sections, ui-specification.md component specs) -- **Integration tests** — end-to-end flow validation covering workflows defined in walkthrough.md (cites specification.md endpoint chains, walkthrough.md journeys) +- **Integration tests** — end-to-end flow validation covering workflows defined in 3-walkthrough.md (cites specification.md endpoint chains, 3-walkthrough.md participant sections) - **Performance tests** — load tests, stress tests, and benchmarking against NFR thresholds (cites requirements.md NFRs, solution-design.md performance decisions) - **Penetration tests** — adversarial testing of security requirements and auth flows (cites requirements.md security NFRs, specification.md auth endpoints) - Contract testing scripts (mapped to specification.md sections) @@ -227,8 +229,8 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio - Security scanning and audit jobs (SAST, dependency vulnerability checks) - CI/CD pipeline configurations for automated test execution - Each validation test must include explicit references to: - - **specification.md** (exact spec IDs or paths — API contracts, data schemas, e.g., sections 3.1, 4.2) — technical rules being tested - - **ui-specification.md** (components, interactions, visual states, e.g., sections 15.1, 15.3) — UI contract being verified + - **specification.md** (spec IDs or paths — API contracts, data schemas, e.g., `/api/v1/endpoint` or `#/components/schemas/Request`) + - **ui-specification.md** (components, interactions, visual states, e.g., `## Wine Table` or `### Sort States`) - **requirements.md** (e.g., FR-001, NFR-101, NFR-201) — business intent and NFR thresholds being validated - **solution-design.md** (e.g., SD-2.1, SD-3.3) — architectural decisions being tested @@ -257,11 +259,11 @@ Every specification rule must have a runnable, verifiable test. This trace maps | SD-001 | `solution-design.md:5.1` | — | — | `tests/integration/nats-async.test.ts` | `ci/integration.yaml` | Pass | | UI-15.3.2 | `ui-specification.md:15.3.2` | `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 (walkthrough flows), performance tests (NFR benchmarks), penetration tests (security NFRs), and visual regression tests (UI component states). +**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). **Trace Rules**: - **Every** specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test -- **Every** walkthrough journey must have at least one integration test +- **Every** participant section journey must have at least one integration test - **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) @@ -283,7 +285,7 @@ Every specification rule must have a runnable, verifiable test. This trace maps --- ### 7. Implementation Plan -`implementation-plan.md` +`7-implementation-plan.md` **Why It Matters**: - Converts specification into executable code with clear ownership and timeline @@ -310,7 +312,7 @@ Every specification rule must have a runnable, verifiable test. This trace maps --- ### 8. Runbook -`runbook.md` +`8-runbook.md` **Purpose**: The *operational manual* — how the system lives in production, scales, and recovers. Guides on-call engineers. @@ -358,9 +360,9 @@ Once requirements are stable, translate them into an viable solution. This ensur ### 3. Create Walkthroughs Early -As soon as the solution design is defined, create walkthroughs. This helps identify gaps in the flow and provides onboarding material. The walkthrough should be a single source of truth that explicitly links 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 solution-design.md (SD-XXX IDs) and requirements.md. -**Action**: Create `docs/walkthrough/` with `TOUR.md`, 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 solution design decisions and requirements. ### 4. Define the Specification @@ -368,7 +370,7 @@ 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 walkthrough.md. +**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. ### 5. Define UI Specification Early @@ -380,7 +382,7 @@ Create UI specifications before implementing frontend components. This ensures d 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. -**Action**: Create `docs/validation/` with `unit-tests/` (spec rules, schema fields, component states), `integration-tests/` (end-to-end flows from walkthrough.md), `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/` (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). ### 7. Create Implementation Plan @@ -403,8 +405,8 @@ 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 the Walkthrough trace the complete flow the Solution Design describes, including all SD-XXX decisions? | Solution design says "use NATS for async messaging", but Walkthrough doesn't trace the async flow or reference SD-001 | Add the async messaging flow with SD-001 reference to Walkthrough | -| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does the Specification cover all the behaviors defined in the Walkthrough? | Walkthrough shows 10 IoT sensors sending real-time updates, but Specification only defines REST API | Add NATS/MQTT protocol definitions to Specification | +| **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 | | **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 | @@ -420,11 +422,11 @@ 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 the end-to-end flow with error paths included +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 4. **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) - - Coverage for all behaviors defined in the Walkthrough + - 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 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 @@ -439,7 +441,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 | -| **Walkthrough** | If I can't Trace the full flow, the system has a 'broken bridge'. | Identifies gaps between components and validates the solution design end-to-end | +| **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 | @@ -475,7 +477,7 @@ Each documentation artifact has associated KPIs. Track these to ensure quality: | Document | KPI | Target | |----------|-----|--------| | Requirements | Requirement coverage | 100% of features have associated requirements | -| Solution Design | Solution completeness | 100% of user problems mapped to solution components before spec writing | +| Solution Design | Solution completeness | 0 solution components without a requirement ID reference | | 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 |