update

ASG_Framework.md

@@ -4,7 +4,7 @@ This document defines the documentation framework for a software project. It est
 
 ---
 
-## The ASG Framework: Nine Pillars of Documentation
+## The ASG Framework: Eight Pillars of Documentation
 
 | Document | Purpose | Primary Audience | Format / Content | Example (SaaS Context) | Measurement (KPI) |
 |----------|---------|-----------------|------------------|------------------------|-------------------|
@@ -12,8 +12,8 @@ This document defines the documentation framework for a software project. It est
 | **Solution Design** | Translate requirements into an **viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. | Product Owners, Architects, Developers | Problem decomposition, solution approach, alternatives considered, high-level component diagram, decision rationale. | "Problem: Users need to compare wines. Solution: Build a comparison table with filtering, sorting, and visual comparison. Components: Data layer (Wine API), UI layer (Table component), Logic layer (Filter/Sort engine)." | 100% of user problems mapped to solution components before spec writing. |
 | **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject that accepts Arrow streams with snake_case headers. | 100% of messages validated against spec (CI block rate). |
 | **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 aligns users and developers, exposing architectural gaps before coding begins. | 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. |
+| **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. |
-| **Architecture** | The **blueprint** — how components fit together, interact, and scale. Guides system structure and trade-offs. | Architects, Senior Developers, DevOps | C4 diagrams, Mermaid.js, component/network/storage models. | Diagram showing 6-node cluster routing traffic via Caddy → Node.js API → Julia pods. | 100% of major decisions logged with trade-off analysis. |
+
 | **Implementation** | The **real code** — business logic, helpers, tests, configs. Where design becomes executable. | Developers, Code Reviewers | Source code, README.md, unit tests, setup scripts. | Julia function for matrix calculation + SvelteKit component rendering table. | >80% unit test coverage, <5% drift from spec. |
 | **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. |
@@ -147,14 +147,33 @@ This document defines the documentation framework for a software project. It est
 ### 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, exposing architectural gaps before coding begins.
+**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.
+
+**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.
+
+**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
+
+**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
 
 **Why It Matters**:
 - Serves as a single source of truth for system behavior, bridging user experience and technical implementation
 - Validates that all components (UI, API, backend logic) work together cohesively before implementation begins
-- Exposes architectural gaps and integration risks early in the design phase
+- Exposes solution design gaps and integration risks early in the design phase
 - Aligns stakeholders (product, design, development) on the complete user journey
-- Provides a reference for verifying implementation against intended behavior
+- 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
@@ -171,41 +190,11 @@ This document defines the documentation framework for a software project. It est
 - Link each step to its corresponding specification and UI spec sections
 - Document failure modes and recovery paths
 - Keep walkthroughs updated as requirements evolve
-- Review walkthroughs against architecture to verify feasibility
+- Review walkthroughs against the solution design to verify completeness
 
 ---
 
-### 6. Architecture
+### 6. Implementation
-`architecture.md`
-
-**Purpose**: The *blueprint* — how components fit together, interact, and scale. Guides system structure and trade-offs.
-
-**Why It Matters**:
-- Provides a mental model for system design
-- Guides technical decision-making and trade-off analysis
-- Facilitates onboarding of new architects and senior developers
-- Documents scaling and performance considerations
-- Enables traceability from technical specifications and UI specifications to architectural decisions
-
-**Content Guidelines**:
-- C4 diagrams (Context, Container, Component levels)
-- Mermaid.js flowcharts for sequence diagrams
-- Component interaction diagrams
-- Network topology and data flow
-- Storage and caching strategies
-- Scaling and resilience patterns
-- Each architecture component 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.
-
-**Best Practices**:
-- Use diagrams that are easy to update (Mermaid.js over static images)
-- Document trade-off decisions with Rationale Documents
-- Include scaling considerations for each component
-- Document failure modes and recovery strategies
-- Keep architecture diagrams versioned with code
-
----
-
-### 7. Implementation
 
 **Purpose**: The *real code* — business logic, helpers, tests, configs. Where design becomes executable.
 
@@ -232,7 +221,7 @@ This document defines the documentation framework for a software project. It est
 
 ---
 
-### 8. Validation
+### 7. Validation
 `validation.md`
 
 **Purpose**: The *enforcer* — ensures implementation matches the spec. Blocks drift and human error.
@@ -261,7 +250,7 @@ This document defines the documentation framework for a software project. It est
 
 ---
 
-### 9. Runbook
+### 8. Runbook
 `runbook.md`
 
 **Purpose**: The *operational manual* — how the system lives in production, scales, and recovers. Guides on-call engineers.
@@ -326,25 +315,19 @@ As soon as the UI specification is defined, create walkthroughs. This helps iden
 
 **Action**: Create `docs/walkthrough/` with `TOUR.md`, sequence diagrams, and cross-references to specification and UI spec sections.
 
-### 6. Design the Architecture
+### 6. Implement with Validation in Mind
-
-With requirements, solution design, specification, UI spec, and walkthrough in place, design the architecture. Document trade-off decisions explicitly.
-
-**Action**: Create `docs/architecture/` with Mermaid diagrams and `trade-offs.md`.
-
-### 7. Implement with Validation in Mind
 
 Write implementation code that adheres to the specification. Build validation into the CI pipeline from day one.
 
 **Action**: Ensure test files are co-located with implementation and run on every commit.
 
-### 8. Automate Validation
+### 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.
 
-### 9. Document Operations from Day One
+### 8. Document Operations from Day One
 
 Create runbook entries as soon as deployment procedures are established. Update them when incidents occur.
 
@@ -362,13 +345,13 @@ Since all docs defined in the ASG Framework are **living documents** that evolve
 | **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 |
-| **Walkthrough → Architecture** | Turn the "Story" into "Steel" | Does the Architecture support the performance and integration requirements defined in the Walkthrough? | Walkthrough shows 10 IoT sensors sending real-time updates, but Architecture uses REST API | Switch to NATS/MQTT for high-frequency data flow |
+| **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 |
 
 ### Why Gap-Checks Matter
 
 - **Prevent rework**: Catch missing requirements before coding begins
 - **Ensure completeness**: Verify all scenarios are covered across all layers
-- **Validate feasibility**: Confirm architectural decisions support the intended user flow
+- **Validate feasibility**: Confirm technical approach supports the intended user flow
 - **Maintain alignment**: Keep all stakeholders (product, design, dev) on the same page
 
 ### How to Run Gap-Checks
@@ -378,7 +361,6 @@ Since all docs defined in the ASG Framework are **living documents** that evolve
 3. **Specification Review**: After writing the spec, verify every requirement has at least one rule with a corresponding requirement ID reference
 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
-6. **Architecture Review**: After designing architecture, verify every walkthrough flow is technically feasible and every architecture decision references specification and UI specification sections
 
 ---
 
@@ -393,7 +375,6 @@ This habit ensures that each documentation stage is complete and validated befor
 | **Specification** | If I can't write a Rule with a requirement ID reference, I haven't thought the logic through. | Ensures traceability from technical rules to business requirements |
 | **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 |
-| **Architecture** | If the Walkthrough doesn't Require it, or if I can't trace spec/UI-spec references, I'm over-engineering or missing requirements. | Ensures traceability from architecture to spec/UI-spec and requirements |
 
 **How to Use This Habit:**