diff --git a/ASG_Framework.md b/ASG_Framework.md index 2556984..e407518 100644 --- a/ASG_Framework.md +++ b/ASG_Framework.md @@ -10,11 +10,11 @@ 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. | +| **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. | | **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. | -| **Validation** | The **enforcer** — ensures implementation matches the spec. Blocks drift and human error. | Automation servers, QA, Lead Developers | CI jobs, contract tests, linting, integration checks. | CI job rejects PR with camelCase field not allowed by YAML spec. | <1% of PRs bypass validation gates. | +| **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. | | **Runbook** | The **operational manual** — how the system lives in production, scales, and recovers. Guides on-call engineers. | DevOps, SREs, On-call Developers | K8s manifests, Helm charts, Markdown guides. Deployment, scaling, backup/restore, troubleshooting. | GitOps manifest ensuring 6 Julia replicas restart if memory >80%. | MTTR <15 minutes for P1 incidents. | --- @@ -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 moving to specification +- Get sign-off from product, architecture, and engineering before creating walkthroughs **Gap-Check Question**: Does the Solution Design clearly explain how the system solves the user problem, not just what it does? @@ -88,69 +88,7 @@ This document defines the documentation framework for a software project. It est --- -### 3. Specification -`specification.md` -**Purpose**: The *technical contract* — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. - -**Why It Matters**: -- Prevents implementation drift between components -- Enables contract testing in CI/CD pipelines -- Provides a single source of truth for data structures -- Facilitates integration between teams -- Enables traceability from business requirements to technical implementation - -**Content Guidelines**: -- API endpoint definitions (methods, paths, parameters) -- Request/response schemas (JSON, XML, Protobuf, AsyncAPI) -- Error codes and their meanings -- Data validation rules and constraints -- Rate limiting and quota definitions -- 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) -- Version specifications alongside code -- Generate client SDKs from specifications -- Block CI on specification violations -- Document edge cases and error scenarios - ---- - -### 4. UI Specification -`ui-specification.md` - -**Purpose**: The *design contract* — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation. - -**Why It Matters**: -- Prevents visual inconsistency across the application -- Enables design system scalability and maintainability -- Provides a single source of truth for UI components and interactions -- Facilitates collaboration between designers and developers -- Enables traceability from business requirements to UI implementation - -**Content Guidelines**: -- Component specifications (atomic design principles) -- Style guide (colors, typography, spacing, icons) -- Interaction patterns (animations, transitions, states) -- 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. - -**Best Practices**: -- Use design systems with versioned component libraries -- Sync design tokens from Figma to CSS variables automatically -- Document component states (normal, hover, disabled, error) -- Include accessibility requirements for each component -- Create visual regression tests for critical UI flows -- Version UI specifications alongside code - ---- - -### 5. Walkthrough +### 3. Walkthrough `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. @@ -188,75 +126,186 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio - Error paths and edge cases with their handling - Sequence diagrams showing request/response patterns across all layers - State machine diagrams for complex workflows -- Each major walkthrough step must cite the exact specification ID(s) or spec path(s) in specification.md and/or the UI‑spec artifact ID(s) or path(s) in ui-specification.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 `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 -- Link each step to its corresponding specification and UI spec sections +- 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 --- -### 6. Implementation Plan +### 4. Specification +`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**: +- Prevents implementation drift between components +- Enables contract testing in CI/CD pipelines +- Provides a single source of truth for data structures +- Facilitates integration between teams +- Enables traceability from business requirements to technical implementation + +**Content Guidelines**: +- API endpoint definitions (methods, paths, parameters) +- Request/response schemas (JSON, XML, Protobuf, AsyncAPI) +- Error codes and their meanings +- Data validation rules and constraints +- Rate limiting and quota definitions +- 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) +- Version specifications alongside code +- Generate client SDKs from specifications +- Block CI on specification violations +- Document edge cases and error scenarios + +--- + +### 5. UI Specification +`ui-specification.md` + +**Purpose**: The *design contract* — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation. + +**Why It Matters**: +- Prevents visual inconsistency across the application +- Enables design system scalability and maintainability +- Provides a single source of truth for UI components and interactions +- Facilitates collaboration between designers and developers +- Enables traceability from business requirements to UI implementation + +**Content Guidelines**: +- Component specifications (atomic design principles) +- Style guide (colors, typography, spacing, icons) +- Interaction patterns (animations, transitions, states) +- 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. + +**Best Practices**: +- Use design systems with versioned component libraries +- Sync design tokens from Figma to CSS variables automatically +- Document component states (normal, hover, disabled, error) +- Include accessibility requirements for each component +- Create visual regression tests for critical UI flows +- Version UI specifications alongside code + +--- + +### 6. Validation +`validation.md` + +**Purpose**: The *enforcer* — defines tests **before implementation begins** to ensure spec compliance. Blocks drift and human error. + +**Why It Matters**: +- Ensures tests are written before implementation, so code can be tested as it's built +- Prevents breaking changes from reaching production +- Catches specification violations early in the CI pipeline +- Maintains data integrity and API consistency +- Reduces manual QA effort through automation +- Provides immediate feedback to developers during implementation +- Validates performance NFRs (latency, throughput) against measurable KPIs before deployment +- Validates security requirements through adversarial testing before production + +**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) +- **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) +- Linting rules and configurations (enforcing style guides from ui-specification.md) +- Schema validation jobs (validating data shapes from specification.md) +- Visual regression tests (verifying UI matches ui-specification.md) +- 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 + - **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 + +**Best Practices**: +- Define tests **before** writing implementation code +- Fail CI on specification violations +- Run validation jobs on every commit and PR +- Use automated code review tools +- Maintain validation job health dashboard +- Document validation failure remediation steps + +--- + +#### 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. + +**Trace Format**: + +| Requirement ID | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status | +|----------------|-------------|----------------|-------------------|------------------------|---------|--------| +| FR-001 | `specification.md:3.2.1` | `tests/unit/schema-validation.test.ts` | `test_rejects_camelCase_headers` | — | `ci/contract-validation.yaml` | Pass | +| FR-002 | `specification.md:4.1` | `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:3.2.3` | — | — | `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-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). + +**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** 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) +- 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 + +**How to Maintain**: +1. When writing a new spec rule, add a trace row **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 + +**Tooling** (optional): +- Use YAML or JSON files (e.g., `validation/test-trace.yaml`) as machine-readable trace data +- Generate CI reports that auto-populate the Status column from pipeline results +- Use tools like `cypress open` for E2E traces, `k6` for performance traces, `owasp-zap` for pen test traces +- Integrate trace data into PR descriptions so reviewers can verify coverage before merge + +--- + +### 7. Implementation Plan `implementation-plan.md` **Why It Matters**: - Converts specification into executable code with clear ownership and timeline - Enables parallel development across teams by defining module boundaries - Provides visibility into progress and blockers for stakeholders -- Ensures all specification sections are covered by implementation tasks +- Ensures all validation tests are covered by implementation tasks **Content Guidelines**: -- Implementation phases and timeline (e.g., Phase 1: Core API, Phase 2: UI, Phase 3: Validation) +- 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 strategy: which tests cover which specification sections (unit, integration, E2E) +- Test coverage: which validation tests each implementation 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 specification sections (not requirement IDs — those belong in specification.md) +- Map each implementation task to specific validation tests (not just specification sections) - Define clear ownership for each module or component - Include test coverage targets for each phase - Document dependencies between modules to avoid blocking work -- Review implementation plan against walkthrough to ensure complete coverage - ---- - -### 7. Validation -`validation.md` - -**Purpose**: The *enforcer* — ensures implementation matches the spec. Blocks drift and human error. - -**Why It Matters**: -- Prevents breaking changes from reaching production -- Catches specification violations early in the CI pipeline -- Maintains data integrity and API consistency -- Reduces manual QA effort through automation - -**Content Guidelines**: -- CI/CD pipeline configurations -- Contract testing scripts -- Linting rules and configurations -- 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) — 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 -- Run validation jobs on every commit and PR -- Use automated code review tools -- Maintain validation job health dashboard -- Document validation failure remediation steps +- Review implementation plan against validation tests to ensure complete coverage --- @@ -307,37 +356,37 @@ Once requirements are stable, translate them into an viable solution. This ensur **Action**: Create `docs/solution-design/` with `solution-design.md`, problem decomposition, alternatives considered, high-level component diagram, and decision rationale. -### 3. Define the Specification +### 3. Create Walkthroughs Early -With solution design in place, define the technical specification. This becomes the contract for implementation. Each specification item must trace to **both**: +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. + +**Action**: Create `docs/walkthrough/` with `TOUR.md`, sequence diagrams, and cross-references to solution design decisions and requirements. + +### 4. Define the Specification + +With walkthrough 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), `error-codes.md`, and traceability mappings to requirements.md and solution-design.md. +**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. -### 4. Define UI Specification Early +### 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`. -### 5. Create Walkthroughs Early +### 6. Define Validation Tests Before Implementation -As soon as the UI specification 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 specification.md and ui-specification.md. +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/walkthrough/` with `TOUR.md`, sequence diagrams, and cross-references to specification and UI spec sections. +**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). -### 6. Implement with Validation in Mind +### 7. Create Implementation Plan -Write implementation code that adheres to the specification. Build validation into the CI pipeline from day one. +With validation tests defined, create the implementation plan. Map each implementation task to specific validation tests that it must satisfy. -**Action**: Ensure test files are co-located with implementation and run on every commit. - -### 7. Automate Validation - -Build automated validation that runs in CI/CD. This ensures spec compliance and prevents drift. - -**Action**: Configure CI jobs to validate against specification and block PRs on violations. +**Action**: Create `docs/implementation-plan/` with phases, module breakdown, task list with assignees, and test coverage targets. ### 8. Document Operations from Day One @@ -354,10 +403,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 → Specification** | Turn a "Solution" into a "Contract" | Does the Specification define all technical details that the solution approach requires? | Solution design says "use caching for performance", but Specification doesn't define cache invalidation strategy | Add cache TTL, invalidation rules, and error handling 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 → Walkthrough** | Turn "Screens" into a "Story" | Does the Walkthrough reflect the complete flow including error states and timing? | Walkthrough shows "Success" screen, but Specification says backend process takes 2 minutes | Add a `Processing` state to UI Specification and `JobStatus` field to Specification | +| **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 | +| **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 | ### Why Gap-Checks Matter @@ -370,11 +420,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. **Specification Review**: After writing the spec, verify every spec item has: +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 +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) -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 + - Coverage for all behaviors defined in the Walkthrough +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 --- @@ -386,9 +439,10 @@ 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 | | **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 | +| **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 | **How to Use This Habit:** @@ -424,7 +478,6 @@ Each documentation artifact has associated KPIs. Track these to ensure quality: | Solution Design | Solution completeness | 100% of user problems mapped to solution components before spec writing | | Specification | Specification compliance rate | 100% of messages validate against spec | | UI Specification | UI spec compliance | 100% of components match design spec (visual regression tests) | -| Architecture | Decision documentation | 100% of major decisions logged with trade-offs | | 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 | @@ -788,7 +841,7 @@ flowchart TD ## Conclusion This ASG Documentation Framework ensures that documentation is: -- **Structured**: Nine distinct artifacts with clear purposes +- **Structured**: Eight distinct artifacts with clear purposes - **Automated**: Validation and CI/CD integration - **Versioned**: All documentation in git with history - **Measurable**: KPIs for quality and effectiveness