Files

T

ton a468628fb0 update

2026-09-08 20:53:22 +07:00

57 KiB

Raw Blame History

Agile + Spec Driven Development + GitOps Documentation Framework

This document defines the documentation framework for a software project. It establishes a structured approach to creating, maintaining, and evolving technical documentation in alignment with GitOps principles—ensuring that documentation is versioned, auditable, and continuously validated alongside the codebase.

The ASG Framework: Eight Pillars of Documentation

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 a viable solution — how the system solves the user problem. Defines approach, components, and trade-offs before technical details.	Product Owners, Architects, Developers	Problem decomposition, solution approach, decision rationale, high-level component diagram, alternatives considered.	"Problem: Users need to compare wines. Solution: Build a comparison table with filtering, sorting, and visual comparison. Components: Data layer (Wine API), UI layer (Table component), Logic layer (Filter/Sort engine)."	0 solution components without a requirement ID reference.
Walkthrough	The end-to-end trace — maps the entire system flow from startup to cycle completion for each participant. Provides a "big picture" view that validates solution design before technical specification is locked.	Product Owners, Architects, Developers, End Users	Per-participant sections, sequence diagrams, state machine diagrams. Explicitly links to `2-solution_design.md` and `1-requirements.md`.	"User logs in → selects wine → edits details → saves → backend validates against spec → UI updates with error states."	100% of user journeys traced across all layers before implementation starts.
Specification	The technical contract — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. Maps technical implementation to both what (requirements) and how (solution design).	Developers, QA Engineers, CI/CD pipelines	OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes.	`contract.yaml` defining a NATS subject (solution-design SD-001.1) that accepts Arrow streams with snake_case headers (requirements FR-001).	100% of messages validated against spec (CI block rate).
UI Specification	The design contract — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation.	Product Designers, Frontend Developers, QA Engineers	Component libraries, style guides, interaction specs, design tokens.	Atomic design system with Figma tokens synced to CSS variables.	100% of UI components match design spec (visual regression tests).
Validation	The enforcer — defines tests before implementation begins to ensure spec compliance. Blocks drift and human error.	QA Engineers, Developers, Automation servers	Unit tests, integration tests, performance tests, penetration tests, contract tests, CI jobs, linting rules, schema validation.	CI job rejects PR with camelCase field not allowed by YAML spec.	<1% of PRs bypass validation gates.
Implementation Plan	The execution roadmap — how implementation is organized, prioritized, and delivered. Maps code to validation tests and specification.	Developers, Project Managers, Lead Developers	Implementation plan, module breakdown, task list, delivery timeline, test strategy.	Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation.	100% of validation tests covered by implementation tasks.
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.

Detailed Document Descriptions

1. Requirements

1-requirements.md

Purpose: Capture the business intent — why we're building this and what success looks like. Defines boundaries and user-visible outcomes.

Why It Matters:

Aligns engineering efforts with business goals
Provides a north star for feature development
Establishes acceptance criteria before implementation begins
Creates a contract between product, engineering, security, and operations.

Content Guidelines:

User stories with clear acceptance criteria (As a X, I want Y so that Z)
Functional Requirements (FR): Testable features with clear IDs (e.g., FR-001, FR-101). Each functional requirement must be linked to a measurable KPI in the success metrics section.
Non-Functional Requirements (NFR): Qualities or constraints the system must have (performance, scalability, availability, reliability, security, privacy, observability). NFRs define what kind of system you need, not what it does.
- Example NFR: "System shall support 10K TPS" (requirement)
- Example KPI: "95th percentile latency <200ms" (measurable success metric)
Success Metrics & KPIs: Specific, measurable targets that validate whether requirements were met. KPIs are measured after deployment; NFRs are defined before implementation.
Boundary definitions that state what is in scope and out of scope.
Security requirements including threat model outcomes, authentication and authorization expectations, data classification, encryption requirements, and compliance controls.
Observability requirements specifying required telemetry, metrics, traces, logs, alerting thresholds, and retention policies.
Traceability Rule: Requirements must be self-contained (no cross-references to other docs as justification), but must include IDs (e.g., FR-001) so downstream artifacts (spec, UI spec, architecture) can trace back. All downstream documents MUST cite requirement IDs, but requirements themselves stand alone. Walkthrough steps (WT-XXX) may also cite requirement IDs directly.

Best Practices:

Link each requirement to a measurable KPI — functional requirements should have explicit KPIs; non-functional requirements should have measurable thresholds
Keep requirements testable and verifiable
Maintain backward compatibility with existing requirements
Review and update requirements as business context changes

2. Solution Design

2-solution_design.md

Purpose: Translate requirements into a viable solution — how the system solves the user problem. Defines approach, components, and trade-offs before technical details.

Why It Matters:

Prevents technical-first thinking that skips design decisions
Ensures the solution addresses the actual user problem, not just requirements
Enables architects to evaluate alternatives before committing to technical details
Creates alignment between product, design, and engineering on the approach
Provides a reference for evaluating specification choices against intended solution

Content Guidelines:

Problem decomposition: Break down the user problem into smaller, solvable pieces
Solution approach: Introduce the solution the way Steve Jobs introduced the iPhone — present what you're delivering to the user first, then explain how it solves their problem. The narrative starts with the product, not the technical components. (e.g., "We're building a comparison table that lets users evaluate wines side-by-side with instant filtering and sorting" — not "We'll use event sourcing with a caching layer")
Decision rationale: Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem. (e.g., "We chose server-side rendering so shared comparisons are indexable by search engines, enabling retailers to distribute links without login walls")
High-level component diagram: Show major components and their relationships (not technical details, just the big picture)
Alternatives considered: Document at least 2-3 alternative approaches with rationale for why they were rejected
Risk assessment: Identify potential risks and how they will be mitigated
Traceability: Link each solution component to specific requirement ID(s) (e.g., FR-001, NFR-201) that it addresses
Decision IDs: Assign unique IDs to major decisions using the format SD-XXX (e.g., SD-001 for "Use NATS for async messaging") to enable specification traceability

Best Practices:

Write solution design from the user's perspective first, then justify technical choices
Keep it high-level—avoid technical specifics (API endpoints, data schemas, etc.)
Use diagrams that are easy to update (Mermaid.js)
Document trade-off decisions explicitly
Review solution design against requirements to verify completeness
Create walkthroughs to validate the solution design end-to-end; sign-off from product, architecture, and engineering happens after walkthroughs confirm the approach works

Gap-Check Question: Does the Solution Design clearly explain how the system solves the user problem, not just what it does?

Example Gap: Requirements say "users can compare wines", but solution design only mentions "wine comparison API" without explaining how users will actually use the comparison feature.

3. Walkthrough

3-walkthrough.md (single file with per-participant sections)

Primary Audience: Product Owners, Architects, Developers, End Users

Purpose: The end-to-end trace — each section maps one system participant's complete journey from their own POV, from session start to task completion. Provides a "big picture" view that validates solution design before technical specification is locked. Each section is standalone: described entirely from that participant's perspective, with cross-references to other participants' sections where their workflows intersect.

Per-Participant Walkthroughs The walkthrough is organized as one document with a dedicated section per system participant, each tracing the complete journey from that participant's perspective.

Traces the complete flow from that participant's login/session start to task completion and logout
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:

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 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:

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) 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 2-solution_design.md and/or Requirement ID(s) from 1-requirements.md that it implements or depends on.
Assign a unique ID to each walkthrough step using the format WT-XXX (e.g., WT-001 for Participant A login, WT-002 for Participant B order placement) to enable downstream traceability

Best Practices:

Write each section from one participant's perspective, then cross-reference other participants' sections
Include concrete examples with realistic data values for each participant's typical usage
Link each step to its corresponding Solution Design decision (SD-XXX.Y IDs), Requirement ID(s), and Walkthrough ID (WT-XXX)
Map cross-participant interactions explicitly (e.g., "Customer action X → Retailer notification Y")
Document failure modes and recovery paths from each participant's perspective
Keep walkthroughs updated as requirements and participant roles evolve
Review walkthroughs against the solution design to verify completeness across all participants

4. Specification

4-specification.md

Purpose: The technical contract — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. Maps technical implementation to both what (requirements) and how (solution design).

Why It Matters:

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
Assign a unique ID to each specification item using the format SP-XXX (e.g., SP-001 for the Request schema, SP-002 for POST endpoint) for downstream traceability
Each specification item must cite:
- Requirement ID(s) from 1-requirements.md (e.g., FR-001, NFR-201) — defines what the system must do
- Solution Design reference(s) from 2-solution_design.md (e.g., SD-001.1, SD-002.1) — defines how and why this technical approach was chosen
- Link each endpoint, schema, validation rule, error case, etc to the exact requirement(s) and solution design it implements or satisfies.

Best Practices:

Use formal specification languages (OpenAPI 3.0+, AsyncAPI)
Version specifications alongside code
Generate client SDKs from specifications
Block CI on specification violations
Document edge cases and error scenarios

5. UI Specification

5-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 1-requirements.md and/or the exact solution design decision ID(s) from 2-solution_design.md that it implements or depends on
Assign a unique ID to each UI artifact using the format UI-XXX (e.g., UI-001 for Login Form, UI-002 for Wine Table) to enable downstream traceability

Best Practices:

Use design systems with versioned component libraries
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

6-validation.md

Purpose: The enforcer — defines tests before implementation begins to ensure spec compliance. Blocks drift and human error.

Because implementation must satisfy specifications, Validation derives all test definitions from the preceding 5 documents:

Source Document	What Validation Tests
1. Requirements	NFR thresholds (latency, throughput), security constraints, observability checks
2. Solution Design	Architectural decisions, performance choices, risk mitigations
3. Walkthrough	End-to-end flows for each participant section, cross-participant interactions
4. Specification	API contracts, data schemas, error codes, validation rules
5. UI Specification	Component states, visual patterns, accessibility compliance

Every specification rule, walkthrough journey, and NFR threshold must have a corresponding test — each spec item carries an SP-XXX ID, every walkthrough step carries a WT-XXX ID, and every UI artifact carries a UI-XXX ID. Tests are written before code so implementation can be validated as it's built. If a spec rule, walkthrough journey, NFR threshold, or UI state has no corresponding test, the Validation doc is incomplete.

Test Types

Each validation test must include explicit references to its source document:

Test Type	Source	Example Reference
Unit tests	`4-specification.md`, `5-ui_specification.md`	`4-specification.md:3.2.1` rejects camelCase headers; `5-ui_specification.md:## Wine Table` sort states
Integration tests	`3-walkthrough.md`, `4-specification.md`	`WT-001` Participant A login → endpoint chain in `4-specification.md`; `SP-002`
Performance tests	`1-requirements.md` NFRs, `2-solution_design.md`	`NFR-101` latency threshold; `SD-002` WebSocket performance decision
Penetration tests	`1-requirements.md` security NFRs, `4-specification.md` auth endpoints	`NFR-301` authentication; `4-specification.md:auth/login` endpoint
Contract tests	`4-specification.md` sections	Mapped to endpoint definitions and schema constraints
Linting rules	`5-ui_specification.md` style guides	Enforcing design tokens from `5-ui_specification.md`
Schema validation	`4-specification.md` data schemas	Validating Arrow stream headers (snake_case), JSON payloads
Visual regression	`5-ui_specification.md` component states	Verifying hover, disabled, error states match spec
Security scanning	`1-requirements.md`, `4-specification.md`	SAST, dependency vulnerability checks, OWASP rules
CI/CD pipeline	All test types above	Automated execution on every commit and PR

Specification-to-Test Execution Trace

Every traceable item — specification rules (SP-XXX), walkthrough journeys (WT-XXX), UI artifacts (UI-XXX), NFR thresholds, and SD decisions — must have a runnable, verifiable test. This trace maps each item to its corresponding test file, test function, and CI gate — proving that every requirement was tested, not just claimed.

Trace Format:

Requirement/Spec ID	Participant	Source Path	Unit Test File	Unit Test Function	Additional Test File(s)	CI Gate	Status
SP-001	—	`4-specification.md#/components/schemas/Request`	`tests/unit/schema-validation.test.ts`	`test_rejects_camelCase_headers`	—	`ci/contract-validation.yaml`	Pass
SP-002	—	`4-specification.md#/paths/~1api~1v1~1endpoint`	`tests/unit/api-routes.test.ts`	`test_post_wine_returns_201`	`tests/integration/wine-flow.test.ts`	`ci/contract-validation.yaml`	Pass
WT-001	Customer	`3-walkthrough.md:#login`	`tests/integration/customer-login.test.ts`	`test_login_flow`	—	`ci/integration.yaml`	Pass
WT-002	Retailer	`3-walkthrough.md:#order`	`tests/integration/retailer-order.test.ts`	`test_order_placement`	—	`ci/integration.yaml`	Pass
NFR-101	—	`1-requirements.md:4.1`	—	—	`tests/performance/load.test.ts`	`ci/performance.yaml`	Pass
SD-001	—	`2-solution_design.md:5.1`	—	—	`tests/integration/nats-async.test.ts`	`ci/integration.yaml`	Pass
UI-001	—	`5-ui_specification.md## Wine Table`	`tests/unit/wine-table.test.tsx`	`test_sort_by_name`	`tests/visual/wine-table.spec.js`	`ci/visual-regression.yaml`	Pass

Additional Test File(s) column covers: unit tests (spec rules, UI states), integration tests (WT walkthrough flows), performance tests (NFR benchmarks), penetration tests (security NFRs), contract tests (endpoint/schema pairs), linting rules (design tokens), schema validation (data schemas), security scanning (SAST/dependency checks), and visual regression tests (UI component states).

Trace Rules:

Every specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test and one contract test — each spec item carries an SP-XXX ID
Every walkthrough journey must have at least one integration test — each walkthrough step carries a WT-XXX ID
Every performance NFR must have at least one performance test (load/stress/benchmark)
Every security NFR must have at least one penetration test scenario and one security scanning test (SAST/dependency checks)
Every UI component state must have at least one unit test (behavior) and one visual regression test (appearance) — each UI artifact carries a UI-XXX ID
Every data schema must have at least one schema validation test
Every style guide token must have at least one linting rule
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

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

How to Maintain:

When writing a new spec rule, assign an SP-XXX ID; when writing walkthrough steps assign WT-XXX; when defining UI artifacts assign UI-XXX; when creating implementation tasks assign IMP-XXX — then add trace rows before implementation
When writing the test, fill in the test file and function
CI gate auto-updates Status from pipeline results
Gap-Check Step 5 (Validation Review) verifies 100% row coverage — no traceable item without a test

Tooling (optional):

Use YAML or JSON files (e.g., validation/test-trace.yaml) as machine-readable trace data
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

7-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 validation tests are covered by implementation tasks

Content Guidelines:

Implementation phases and timeline (e.g., Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation)
Module/component breakdown with responsibilities and dependencies
Task list with assignees, priorities, estimated effort — assign unique task IDs using the format IMP-XXX (e.g., IMP-001 for Core API implementation)
Test coverage: which validation tests each IMP-XXX task satisfies
Build and deployment preparation (CI/CD setup, environment configuration)
Risk mitigation: known blockers and mitigation steps

Best Practices:

Break implementation into small, testable increments (1-3 day task units)
Assign an IMP-XXX ID to each implementation task and map it to specific validation tests it satisfies
Define clear ownership for each module or component
Include test coverage targets for each phase
Document dependencies between modules to avoid blocking work
Review implementation plan against validation tests to ensure complete coverage

8. Runbook

8-runbook.md

Purpose: The operational manual — how the system lives in production, scales, and recovers. Guides on-call engineers.

Why It Matters:

Reduces Mean Time To Recovery (MTTR) for incidents
Provides step-by-step guidance for common issues
Documents scaling and deployment procedures
Ensures operational knowledge is not siloed

Content Guidelines:

Deployment procedures (manual and automated)
Scaling instructions (horizontal/vertical)
Backup and restore procedures
Troubleshooting guides for common issues
Runbook entries for specific error codes
Contact information and escalation paths
Explicit references to 4-specification.md (API contracts, data schemas, specific endpoint sections)
Explicit references to 5-ui_specification.md (components, interactions, visual states, specific component sections)

Best Practices:

Write runbooks for every P1/P2 incident
Include exact commands and configuration snippets
Test runbooks periodically (chaos engineering)
Link runbook entries to relevant documentation
Keep runbooks updated when system changes

How to Use This Approach Effectively

1. Start with Requirements

Before writing any code or documentation, establish clear requirements. Ask:

What business problem are we solving?
How will we measure success?
What are the non-negotiable constraints?

Action: Create a docs/requirements/ directory and start with PRD.md and KPIs.md.

2. Define Solution Design

Once requirements are stable, translate them into a viable solution. This ensures the technical approach solves the user problem, not just requirements.

Action: Create docs/solution-design/ with 2-solution_design.md, problem decomposition, solution approach, decision rationale, high-level component diagram, and alternatives considered.

3. Create Walkthroughs Early

As soon as the solution design is defined, create walkthroughs — one document with a section per system participant. This helps identify gaps in each participant's flow and provides onboarding material. Each section traces the complete journey from that participant's perspective and cross-references other participants' workflows. The walkthrough should explicitly link to 2-solution_design.md (SD-XXX.Y IDs) and 1-requirements.md.

Action: Create docs/walkthrough/ with 3-walkthrough.md containing one section per participant (e.g., Customer, Retailer, Admin), sequence diagrams, and cross-references to 2-solution_design.md (SD-XXX.Y IDs) and 1-requirements.md.

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 1-requirements.md, 2-solution_design.md, and 3-walkthrough.md. Each specification item must have an SP-XXX ID.

5. Define UI Specification Early

Create UI specifications before implementing frontend components. This ensures design consistency and provides a contract for implementation.

Action: Create docs/ui-specification/ with component-library.md, style-guide.md, and design-tokens.json. Each UI artifact must have a UI-XXX ID.

6. Define Validation Tests Before Implementation

Write validation tests before implementation begins. This ensures every specification rule (SP-XXX), walkthrough journey (WT-XXX), UI state (UI-XXX), and NFR threshold has a corresponding test that defines success. Tests should reference 4-specification.md, 5-ui_specification.md, 3-walkthrough.md, 1-requirements.md (NFR thresholds), and 2-solution_design.md (performance decisions). Create a specification-to-test execution trace that maps every spec item to its test file, test function, and CI gate.

Action: Create docs/validation/ with unit-tests/ (spec rules, schema fields, component states), integration-tests/ (WT-XXX walkthrough flows), performance-tests/ (NFR benchmarks: latency, TPS), penetration-tests/ (security NFRs, auth flows), contract-tests/, ci-pipeline.yaml, lint-rules/, and test-trace.yaml (specification-to-test execution trace mapping every spec path to its test file, test function, and CI gate).

7. Create Implementation Plan

With validation tests defined, create the implementation plan. Assign IMP-XXX IDs to each task and map them to the specific validation tests they must satisfy.

Action: Create docs/implementation-plan/ with 7-implementation-plan.md containing phases, module breakdown, task list with assignees/priorities/effort (IMP-XXX IDs), and test coverage targets.

8. Document Operations from Day One

Create runbook entries as soon as deployment procedures are established. Update them when incidents occur.

Action: Create docs/runbook/ with entries for deployment, scaling, and common issues.

The Gap-Check Process

Since all docs defined in the ASG Framework are living documents that evolve throughout the project lifecycle, this Gap-Check process ensures each documentation stage validates the previous one before moving forward.

Stage Transition	Goal	Gap-Check Question	Example Gap	Result
Requirements → Solution Design	Turn a "Wish" into a "Solution"	Does the Solution Design clearly explain how the system solves the user problem, not just what it does?	Requirements say "users can compare wines", but solution design only mentions "wine comparison API" without explaining how users will actually use the comparison feature	Add UI flow and user interaction patterns to the solution design
Solution Design → Walkthrough	Turn a "Solution" into a "Story"	Does every SD-XXX decision appear in at least one participant's walkthrough section? Is there a WT-XXX ID for every walkthrough step? Is there a section for each system participant?	Solution design defines SD-001 (NATS async messaging), but no participant section traces the async flow	Add an async messaging flow to Participant B section with SD-001 reference and WT-003 ID
Walkthrough → Specification	Turn the "Story" into "Rules"	Does every WT-XXX walkthrough step trace to at least one SP-XXX specification rule?	Walkthrough defines 20 WT-XXX steps across 3 participants, but only 10 map to SP-XXX rules	Add SP-XXX rules for the 10 unlinked WT-XXX steps
Specification → UI Specification	Turn a "Rule" into a "Button"	Does the UI Specification expose all data entities and states defined in the Specification? Are UI-XXX IDs assigned to every UI artifact?	Specification defines 15 API response schemas with 30 fields, but UI Specification only has 3 components (UI-001 through UI-003)	Add the remaining UI components for each data entity with UI-XXX IDs to match Specification coverage
UI Specification → Validation	Turn "Design" into "Tests"	Do the Validation tests cover all specification rules, UI states, performance NFRs, and security requirements?	UI Spec defines 15 component states but Validation only has 5 unit tests; NFR-101 latency threshold has no performance test	Add unit tests for all component states, performance benchmarks for NFR thresholds, and pen test scenarios for security NFRs
Validation → Implementation Plan	Turn "Tests" into "Tasks"	Does the Implementation Plan satisfy all validation tests with clear ownership?	Validation defines 30 test cases but Implementation Plan only has tasks for 20	Verify every validation test maps to at least one implementation task with an assignee and timeline

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 technical approach supports the intended user flow
Maintain alignment: Keep all stakeholders (product, design, dev) on the same page

How to Run Gap-Checks

Requirements Review: After writing requirements, ask "What happens if X?" for each user story
Solution Design Review: After writing solution design, verify every requirement is addressed by at least one solution component with a corresponding requirement ID reference
Walkthrough Review: After writing walkthrough, verify every SD-XXX.Y decision, requirement ID, and WT-XXX walkthrough step is traced in every participant section with error paths included, and that each system participant has a dedicated section
Specification Review: After writing the spec, verify every spec item has:
- An SP-XXX ID assigned for downstream traceability
- At least one requirement ID reference (WHAT)
- At least one solution design reference (HOW/WHY)
- Coverage for all behaviors defined in each participant section
UI Specification Review: After writing UI Specification, verify every UI-XXX artifact has a corresponding requirement ID, solution design reference, and specification ID
Validation Review: After writing Validation, verify every specification section and UI state has at least one corresponding test case — unit tests for SP-XXX spec rules and UI-XXX UI states, integration tests for WT-XXX walkthrough flows, performance tests for NFR thresholds, penetration test scenarios for security NFRs, contract tests for SP-XXX endpoint/schema definitions, linting rule coverage for 5-ui_specification.md style guides, schema validation for all data schemas, and security scanning for all security NFRs — each with explicit references to 4-specification.md, 5-ui_specification.md, 3-walkthrough.md, and/or 1-requirements.md
Implementation Plan Review: After writing the plan, verify every validation test is covered by at least one implementation task with an assignee and timeline

The Pre-Code Debugging Habit

This habit ensures that each documentation stage is complete and validated before moving forward. These checklists serve as mental guards against building features that don't meet the requirements or architecture.

Stage	Debug Checklist	Why It Matters
Requirements	If I can't state the Value, I'm building a feature nobody needs.	Clarifies the business impact before technical discussion begins
Solution Design	If I can't see the Solution, I'm building without a compass.	Ensures the technical approach solves the user problem before spec writing
Walkthrough	If I can't Trace every participant's flow with WT-XXX IDs, the system has broken bridges.	Identifies gaps between components and validates the solution design end-to-end for each system participant
Specification	If I can't write a Rule with a requirement and solution design reference, I haven't thought the logic through.	Ensures traceability from technical rules to both business requirements (what) and architectural decisions (how/why)
UI Specification	If I can't See it with a UI-XXX ID and traceability reference, the user has no way to trigger the logic.	Ensures traceability from UI elements to business requirements
Validation	If I can't Write a Test for every traceable item, implementation is untestable.	Ensures code can be tested from day one — unit, integration, performance, contract, and security tests define success before implementation begins

How to Use This Habit:

Before writing each doc, run through the checklist for that stage
Before moving to the next doc, run through the checklist for the current stage
When reviewing docs, use the checklist to verify completeness

This habit turns documentation into a self-validating process—each stage catches gaps from the previous one before they become bugs in production.

GitOps Integration

This documentation framework aligns with GitOps principles:

GitOps Principle	Documentation Alignment
Versioned	All documentation lives in git, with history and audit trail
Declarative	Specifications and architecture are declarative contracts
Automated	Validation jobs automate spec compliance checks
Self-Service	Walkthroughs and runbooks enable self-service onboarding and operations
Observability	KPIs and metrics are defined for each documentation artifact

Metrics and Continuous Improvement

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	0 solution components without a requirement ID reference
Walkthrough	Participant coverage	100% of identified system participants have a walkthrough section
Specification	Specification compliance rate	100% of messages validate against spec
UI Specification	UI spec compliance	100% of components match design spec (visual regression tests)
Validation	Bypass rate	<1% of PRs bypass validation gates
Implementation	Implementation coverage	100% of validation tests mapped to at least one task
Runbook	MTTR	<15 minutes for P1 incidents

Review Cadence:

Weekly: Review KPI dashboards and documentation gaps
Monthly: Update documentation based on incident learnings
Quarterly: Full framework review and improvement

Deployment Decision Rules

These rules define the critical gates that must be passed before and after deployment:

Acceptance Condition NOT met → Don't deploy (buggy/broken)
KPI NOT met after deployment → Deployed feature is failing business goals (need fix/optimization)

Acceptance Conditions are verified before deployment through testing and validation. They determine whether the implementation matches the specification and is ready for production.

KPIs are measured after deployment to validate whether the feature is achieving its business goals. If KPIs are not met, the feature may be deployed but is failing its intended purpose and requires immediate attention (fixes or optimization).

These rules serve as a binary decision framework:

Acceptance Conditions = Quality Gate (deploy or block)
KPIs = Business Health Monitor (deploy but fix if failing)

Template Examples

Requirements Template

# PRD: Feature Name

## 1. Business Context & Success Metrics

### Business Goal
[Clear statement of the business problem being solved and why]

### User Stories
- **US-XXX**: [User story with clear action and value]
- *Example: US-001 - As a wine retailer customer, I want to access the sommpanion chat so that I can get wine-related help quickly*

### KPIs & Targets
- **KPI-XXX**: [Measurable target with validation reference]
- *Example: KPI-001 - 95% of chat messages receive responses within 3 seconds (validates FR-001)*

## 2. Technical Boundaries

### In Scope
[List features and capabilities included in this release]

### Out of Scope
[List features explicitly excluded from this release]

### Dependencies
[List external services, APIs, or systems this feature depends on]

### Deployment Constraints
- **NFR-XXX**: [Deployment-specific requirement]
- *Example: NFR-501 - System shall be deployed to MicroK8s cluster with relative URL support*

## 3. Functional Requirements (FR)

### FR-XXX: [Requirement Title]
[Detailed description of what the system shall do]
- [Specific behavior 1]
- [Specific behavior 2]
- [Specific behavior 3]

**Traceability**: US-XXX, US-XXX

### FR-XXX: [Requirement Title]
[Detailed description of what the system shall do]
- [Specific behavior 1]

**Traceability**: US-XXX

## 4. Non-Functional Requirements (NFRs)

### 4.1 Performance & Scalability
- **NFR-XXX**: [Performance requirement with measurable threshold]
- *Example: NFR-101 - Support page shall load in <1 second on 3G networks*

### 4.2 Availability & Reliability
- **NFR-XXX**: [Reliability requirement]
- *Example: NFR-201 - Chat functionality shall have 99.9% monthly uptime*

### 4.3 Privacy & Security
- **Data Classification**: [e.g., PII, PHI, commercial data]
- **Encryption**: [e.g., TLS 1.3+, AES-256 at rest]
- **Authentication**: [e.g., Session-based, OAuth2, API keys]
- **Compliance**: [e.g., GDPR Art. 32, SOC2 Type II, HIPAA]

### 4.4 Observability & Telemetry
- **Required Logs**: [e.g., `session_id`, `user_id`, `message_id`, `event_type`, `timestamp`, `latency_ms`]
- **Critical Metrics**:
  - `metric_name_1`
  - `metric_name_2`
- **Tracing**: [e.g., Zipkin/B3 propagation, 10% sampling]
- **Alerting**: [e.g., `chat_delivery_rate < 95%` triggers PagerDuty]
- **Retention**: [e.g., Logs: 30 days, Metrics: 1 year]

## 5. Acceptance Conditions

- [ ] **FR-XXX**: [Verifiable acceptance condition]
- [ ] **FR-XXX**: [Verifiable acceptance condition]
- [ ] **NFR-XXX**: [Verifiable acceptance condition]
- *Example: [ ] FR-001: Sommpanion landing page renders with all required elements*

Solution Design Template

# Solution Design: Feature Name

## 1. Problem Decomposition

Break down the user problem into smaller, solvable pieces.

| Problem | Description | User Impact |
|---------|-------------|-------------|
| [Problem ID] | Brief description of the problem | How this affects the user |

**Example**: 
- **P-001**: Users cannot compare multiple wines side-by-side → They must navigate between wine pages, losing context and making comparisons difficult

## 2. Solution Approach

Describe the high-level approach to solving the problem.

**Approach**: [e.g., "Implement a comparison table with filtering, sorting, and visual comparison features"]

**Key Principles**:
- [e.g., "Keep comparison data in memory for instant updates"]
- [e.g., "Use server-side rendering for SEO"]
- [e.g., "Support unlimited wine comparisons for power users"]

## 3. Decision Rationale

Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem.

| Decision ID | Decision | Rationale | Alternatives Rejected |
|-------------|----------|-----------|----------------------|
| Decision ID | Decision | Rationale | Alternatives Rejected |
|-------------|----------|-----------|----------------------|
| SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale |
| SD-001.1 | NATS subject naming | Use `catalog:updates` for inventory changes | Static polling |
| SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests |
| SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature |
| SD-004 | Server-side rendering for comparison view | SEO for comparison pages shared via unique links | Client-side rendering - no SEO benefit |
| SD-005 | Server-side PDF/CSV export | Generates downloadable exports with user data | Client-side export — requires user browser permissions |

## 4. High-Level Component Diagram

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%%
flowchart TD
    A[User] --> B[Comparison UI]
    B --> C[Comparison State]
    B --> D[Wine API]
    C --> D

Component Descriptions:

[Component Name]: [Brief description of responsibilities and how it solves part of the problem]
- Links to requirements: FR-001, NFR-201

5. Alternatives Considered

Document at least 2-3 alternative approaches with rationale.

Alternative	Pros	Cons	Decision
Client-side comparison	Fast updates, no server load	Memory-intensive, no sharing	Rejected - memory constraints on mobile
Server-side comparison	Centralized, scalable	Latency, complex state sync	Accepted - matches performance requirements
Hybrid approach	Best of both worlds	Complex, hard to maintain	Rejected - over-engineering

6. Risk Assessment

Identify potential risks and mitigation strategies.

Risk	Impact	Probability	Mitigation
Performance degradation with >5 wines	High	Medium	Implement performance profiling, limit to 10 wines max
Race conditions in real-time updates	Medium	Low	Use optimistic updates with rollback
Memory leaks from comparison state	Medium	Medium	Implement cleanup on unmount, use weak references

7. Requirements Traceability

Link each solution component to specific requirements and assign Solution Design IDs for specification traceability.

Solution Component	Requirement ID	Decision ID	Description
Comparison table UI	FR-101	SD-001	Display wines in table format (uses NATS messaging)
Filtering	FR-102	SD-003	Filter wines by criteria (stored in localStorage)
Sorting	FR-103	SD-004	Sort wines by any column (stored in localStorage)
Real-time updates	NFR-201	SD-002	Updates appear within 100ms (uses WebSocket)
Export comparison	FR-201	SD-005	Export comparison to PDF/CSV (uses server-side rendering)

Walkthrough Template

# Walkthrough: Feature Name

## Structural Guidance

- One **overview sequence diagram** per participant (high-level flow, all major steps)
- **Detailed sub-diagrams** for complex interaction points (e.g., multi-step checkout, validation error paths)
- Use sequence diagrams for request/response patterns; use state machine diagrams for multi-participant state transitions

---

## Customer

### Session Start

**WT-001**: User opens app, navigates to `/compare`

> Cross-reference: `2-solution_design.md:SD-004` (SSR for SEO-friendly comparison links)

**Sequence**:
```mermaid
sequenceDiagram
    participant User as Customer (Browser)
    participant UI as SvelteKit SSR
    participant WineAPI as Wine Service

    User->>UI: GET /compare
    UI->>WineAPI: Get wine list
    WineAPI-->>UI: JSON response
    UI-->>User: Rendered HTML

Select Wines for Comparison

WT-002: User selects 3 wines from inventory table

Step	Action	System Response	Traceability
WT-002.1	Clicks "Add to Compare" on Wine A	Adds to localStorage comparison array	FR-101, SD-003
WT-002.2	Clicks "Add to Compare" on Wine B	Adds to array, updates sidebar count	FR-101, SD-003
WT-002.3	Clicks "Add to Compare" on Wine C	Adds to array, triggers comparison preview	FR-101, SD-003

WT-003: Comparison preview renders with selected wines

Cross-reference: 5-ui_specification.md:UI-002 (Wine Table)

Sequence:

sequenceDiagram
    participant User as Customer
    participant UI as StateStore
    participant Sidebar as ComparisonSidebar

    User->>UI: addToCompare(wine)
    UI->>Sidebar: emit 'comparison:updated'
    Sidebar->>Sidebar: Render preview (3 wines)
    Sidebar-->>User: Visual feedback

Edit Wine Details

WT-004: User modifies price or notes for a selected wine

Cross-reference: 2-solution_design.md:SD-003 (localStorage storage)

WT-005: User clicks "Save Changes"

Sequence:

sequenceDiagram
    participant User as Customer
    participant UI as FormComponent
    participant Local as localStorage
    participant Backend as WineAPI

    User->>UI: Edit form fields
    UI->>Local: Update cached values
    User->>UI: Click Save
    UI->>Backend: PUT /api/v1/wine/:id
    Backend-->>UI: 200 OK
    UI-->>User: Confirmation toast

Error Paths

WT-006: Backend rejects edit (validation error)

Same participant POV — shows rejection from customer's perspective

sequenceDiagram
    participant User as Customer
    participant UI as FormComponent
    participant Backend as WineAPI

    User->>UI: Click Save
    UI->>Backend: PUT /api/v1/wine/:id
    Backend-->>UI: 422 Unprocessable Entity
    UI->>UI: Render field-level errors
    UI-->>User: "Price must be numeric" inline message

WT-007: User clears comparison list

See Retailer section step 4.2 — retailer sees updated catalog

sequenceDiagram
    participant User as Customer
    participant UI as StateStore
    participant Local as localStorage

    User->>UI: Click "Clear All"
    UI->>Local: Set comparison = []
    Local-->>UI: Confirm write
    UI-->>User: Sidebar collapses

Retailer

Receive Updated Catalog

WT-008: Retailer views updated wine inventory

Cross-reference: 3-walkthrough.md:#Customer (WT-005 save event triggers notification)

Sequence:

sequenceDiagram
    participant Retailer as Retailer Dashboard
    participant Nats as NATS Bridge
    participant Backend as WineService

    Retailer->>Nats: Listen to catalog:updates
    Backend-->>Nats: catalog:updated {wine_ids:[...]}
    Nats-->>Retailer: Push notification
    Retailer->>Retailer: Refresh inventory table

Cross-reference: 2-solution_design.md:SD-001 (NATS async messaging)


### Specification Template

```yaml
# contract.yaml
openapi: 3.0.0
info:
  title: NATSBridge API
  version: 1.0.0
  description: Technical specification with requirements and solution design traceability
paths:
  /api/v1/endpoint:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      x-requirement-id: FR-001    # Reference to Requirements document (WHAT)
      x-solution-design-ref: SD-001.1  # Reference to Solution Design decision (HOW/WHY)
      x-spec-id: SP-001           # Specification item ID for downstream traceability
components:
  schemas:
    Request:
      type: object
      properties:
        data:
          type: string
          x-requirement-id: FR-002
          x-solution-design-ref: SD-001.2
          x-spec-id: SP-002
        metadata:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
              x-requirement-id: FR-004
              x-solution-design-ref: SD-001.3
              x-spec-id: SP-004
    Response:
      type: object
      properties:
        status:
          type: string
          x-requirement-id: FR-003
          x-solution-design-ref: SD-001.1
          x-spec-id: SP-003
        record_count:
          type: integer
          minimum: 0
          x-requirement-id: FR-005
          x-solution-design-ref: SD-001.4
          x-spec-id: SP-005

UI Specification Template

# UI Specification: Component Name

## Component Overview
**Name**: [Component Name]
**Status**: [Draft/Approved/Deprecated]
**Version**: 1.0.0
**UI-XXX**: [Unique UI spec ID assigned to this component]

## Requirements Traceability
| UI Element | UI Spec Ref | Requirement ID | Solution Design Ref | Description |
|------------|-------------|----------------|---------------------|-------------|
| Login form | UI-001 | FR-001 | SD-001.1 | Username/password authentication |
| Sidebar menu | UI-002 | FR-102 | SD-002.1 | Collapsible sidebar for navigation |
| Wine table | UI-003 | FR-101 | SD-003.1 | Sortable, searchable inventory table |

## Design Tokens
- **Color**: `--color-primary`
- **Typography**: `--font-body`
- **Spacing**: `--spacing-md`

## Component States
**UI-XXX**: [UI spec ID from the Component Overview]
| State | Description | Example | Requirement ID | UI Spec Ref |
|-------|-------------|---------|----------------|-------------|
| Default | Normal state | `<Button />` | FR-001 | UI-001 |
| Hover | Mouse over | `<Button hover />` | FR-002 | UI-001 |
| Disabled | Disabled state | `<Button disabled />` | FR-003 (disabled state) | UI-001 |
| Error | Error state | `<Button error />` | FR-003 | UI-001 |

## Accessibility
- [ ] WCAG 2.1 AA compliant
- [ ] Keyboard navigation support
- [ ] Screen reader compatible

## Implementation
- Component file: `src/components/[Component].svelte`
- Test file: `src/components/[Component].test.js`
- Visual regression test: `tests/visual/[Component].spec.js`

## References
- Figma: [Link to design file]
- Storybook: [Link to component story]
- Requirements: [`1-requirements.md`](../1-requirements.md)

Specification Traceability Template

Specification Traceability:

Architecture Component	Solution Design Ref	Specification Section	Specification ID (SP)	UI Specification Section	UI Spec Ref (UI)	Requirement ID	Walkthrough Ref (WT)
NATS Bridge (smartsend)	SD-001.1	`4-specification.md`:3.1	SP-001	-	-	FR-301, NFR-201	WT-001
Login Form	SD-002.1	`4-specification.md`:10.1	SP-002	`5-ui_specification.md`:15.2.1	UI-001	FR-001, NFR-201	WT-002
Wine Inventory Table	SD-002.2	`4-specification.md`:4.2	SP-003	`5-ui_specification.md`:15.3.3	UI-002	FR-101, NFR-205	WT-003
Sidebar Menu	SD-002.3	`4-specification.md`:11.1	SP-004	`5-ui_specification.md`:15.3.2	UI-003	NFR-202	WT-004

Runbook Template

# Runbook: Service Restart

**Severity**: P2
**Estimated Time**: 5 minutes

## Symptoms
- Service is unresponsive
- Health checks are failing

## Steps
1. SSH to the host
2. Run: `kubectl rollout restart deployment/natsbridge`
3. Monitor: `kubectl get pods -l app=natsbridge -w`

## Rollback
- Run: `kubectl rollout undo deployment/natsbridge`

## References
- API contract: [`4-specification.md`](4-specification.md)
- UI component states: [`5-ui_specification.md`](5-ui_specification.md)

## Post-Incident
- [ ] Review logs for root cause
- [ ] Update runbook if needed

Appendix: Requirements Traceability Matrix

This matrix traces each requirement through all downstream artifacts. It is maintained as a living cross-reference document, not embedded inline in 1-requirements.md.

Requirement ID	WT ID	SP ID	UI ID	IMP ID	Description	Implementation File	Test File
FR-XXX	WT-XXX	SP-XXX	UI-XXX	IMP-XXX	[Brief description]	`path/to/file.ext`	`tests/file.spec.js`
NFR-XXX	WT-XXX	SP-XXX	UI-XXX	IMP-XXX	[Brief description]	`path/to/file.ext`	`tests/file.spec.js`

Notes:

Functional Requirements (FR) define what the system shall do
Non-Functional Requirements (NFR) define system qualities (performance, availability, security, etc.)
WT-XXX IDs link requirements to walkthrough journey steps in 3-walkthrough.md
SP-XXX IDs are assigned to each specification item in 4-specification.md for downstream traceability (Validation, Implementation Plan)
UI-XXX IDs are assigned to each UI artifact in 5-ui_specification.md for downstream traceability (Validation, Implementation Plan)
IMP-XXX IDs are assigned to each implementation task in 7-implementation-plan.md for downstream mapping to validation tests
KPIs are measurable targets that validate whether requirements were met post-deployment
Each requirement must include a clear requirement ID for traceability
All acceptance conditions must be verifiable through testing or manual inspection

Conclusion

This ASG Documentation Framework ensures that documentation is:

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
Actionable: Practical templates and examples

Use this framework as a living document—update it as your team's needs evolve.

57 KiB Raw Blame History

Agile + Spec Driven Development + GitOps Documentation Framework

The ASG Framework: Eight Pillars of Documentation

Detailed Document Descriptions

1. Requirements

2. Solution Design

3. Walkthrough

4. Specification

5. UI Specification

6. Validation

7. Implementation Plan

8. Runbook

How to Use This Approach Effectively

1. Start with Requirements

2. Define Solution Design

3. Create Walkthroughs Early

4. Define the Specification

5. Define UI Specification Early

6. Define Validation Tests Before Implementation

7. Create Implementation Plan

8. Document Operations from Day One

The Gap-Check Process

Why Gap-Checks Matter

How to Run Gap-Checks

The Pre-Code Debugging Habit

GitOps Integration

Metrics and Continuous Improvement

Deployment Decision Rules

Template Examples

Requirements Template

Solution Design Template

5. Alternatives Considered

6. Risk Assessment

7. Requirements Traceability

Walkthrough Template

Select Wines for Comparison

Edit Wine Details

Error Paths

Retailer

Receive Updated Catalog

UI Specification Template

Specification Traceability Template

Runbook Template

Appendix: Requirements Traceability Matrix

Conclusion

57 KiB

Raw Blame History