GitHub

Understanding nWave's SSOT Model

Why nWave's documentation structure changed, and what v4 records today.


The Problem with 26 Documents Per Feature

Previously, every feature produced ~26 documents across 7 wave directories:

  • DISCOVER: 4 documents
  • DIVERGE: 5 documents
  • DISCUSS: 12 documents
  • DESIGN: 4 documents
  • DEVOPS: 2 documents
  • DISTILL: 1 document
  • DELIVER: 1 document

Over 10 features, you'd have 10 versions of the architecture, 10 versions of the user journey, 10 versions of the system's KPIs — but no single current one. Every agent re-read everything, every feature.

Root cause: Documents were produced to show waves completed work, not to serve downstream consumers.


The Solution: Durable SSOT, No Per-Feature Copies

Product truth moved to durable files under docs/product/, updated in place:

docs/product/
  vision.md                    Product vision + validated problems
  jobs.yaml                    All validated jobs + opportunity scores
  journeys/
  architecture/
  kpi-contracts.yaml           Active measurement contracts

This part of the model is current. /nw-discover bootstraps vision.md and jobs.yaml (and kpi-contracts.yaml for a quantified baseline); /nw-diverge updates jobs.yaml with the validated job and a changelog entry.

What Replaced the Delta Directory

The 3.x answer for per-feature records was a delta directory, docs/features/{id}/, with at most six files per feature: feature-brief.md, recommendation.md, user-stories.md, wave-decisions.md, acceptance-tests.feature and roadmap.json.

v4 replaced it with one feature directory: docs/feature/{id}/, holding the nwdes handoff (handoff.json), the briefs rendered from it (brief.md, architecture.md, acceptance.md, with HTML versions) and the run records under runs/. roadmap.json, execution-log.json and wave-decisions.md are retired; no current wave writes a per-wave ledger, and nothing converts the old files (Migrate from nWave 3.x).


Why This Matters for You

  • You maintain the SSOT files as living products (like code); every reader finds one current version.
  • Each delivery feature has one canonical record, the handoff, and the human reading surface is rendered from it — nothing to keep in sync by hand.
  • Merge conflicts happen at git merge time, with clear history of who changed what.

See Understanding delivery artifacts for what a v4 delivery produces, and Wave Directory Structure for where everything lives.