update

2026-08-17 23:40:36 +07:00
parent c325520128
commit 86cc912b90
1 changed files with 186 additions and 133 deletions
@@ -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. |
+| **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 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. |
+| **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. |
 | **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. |
 | **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
+### 3. Walkthrough
 `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
 `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
+- Review implementation plan against validation tests 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
 ---
@@ -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.
+**Action**: Create `docs/implementation-plan/` with phases, module breakdown, task list with assignees, and test coverage targets.
 ### 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.
 ### 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 |
+| **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 |
 | **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 |
 | **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
+   - Coverage for all behaviors defined in the Walkthrough
-5. **Walkthrough Review**: After writing walkthrough, verify every UI step has a corresponding backend flow
+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