nw-buddy-ssot-knowledge · diff
git:20260407.2d944b1 to git:20260410.37670e3
90 added, 77 removed. Audit A to A.
---
name: nw-buddy-ssot-knowledge
- description: How the SSOT + Delta document model works — file locations, what each file contains, backward compatibility, migration. For the buddy agent to explain and navigate the document model.
- user-invocable: false
- disable-model-invocation: true
+ description: Single Source of Truth detection — where truth lives in an nWave repo and how to avoid contradicting it.
---
- # SSOT + Delta Document Model
+ # SSOT Knowledge for the Buddy Agent
- ## Two-Tier Model
+ Large projects accumulate multiple copies of "the same" information: a version in `pyproject.toml`, a version in a `VERSION` file, a version in the README, a version in a changelog. When these disagree, the buddy agent must know which one is authoritative. This skill is the SSOT map for nWave projects.
- **SSOT** (Single Source of Truth) in `docs/product/` — what the system IS now. Updated by each wave. Never duplicated per feature.
+ ## Why it matters
- **Delta** in `docs/features/{id}/` — what THIS feature changes. Max 6 files per feature.
+ Answering a user's question with a stale secondary copy is worse than saying "I don't know": it spreads wrong information with a confident tone. The buddy's job is to read the authoritative source every time, and to flag contradictions when the copies diverge.
- ## SSOT Directory Structure
+ ## The SSOT map
- ```
- docs/product/
- vision.md Product vision + validated problems
- jobs.yaml All validated JTBD jobs + opportunity scores
- journeys/
- {name}.yaml Current journey schema (updated by DISCUSS)
- {name}-visual.md Human-readable journey narrative
- architecture/
- brief.md Current component boundaries (updated by DESIGN)
- adr-*.md Architectural decision records (permanent)
- kpi-contracts.yaml Active measurement contracts (updated by DEVOPS)
- ```
+ Each concept below has one authoritative file. Read that file first. Treat everything else as a cache that may be stale.
- ## Feature Delta Structure
+ ### Versions
- ```
- docs/features/{id}/
- feature-brief.md Generated summary for human review (after DISTILL)
- recommendation.md Chosen direction (from DIVERGE)
- user-stories.md Stories for this feature (from DISCUSS)
- wave-decisions.md Decisions made across all waves (incremental)
- acceptance-tests.feature Executable specs (from DISTILL)
- roadmap.json Implementation plan (from DELIVER)
- ```
+ - **Authoritative**: `pyproject.toml` `[project] version = "..."` (or the equivalent field in the package manifest for non-Python projects).
+ - **Caches**: `VERSION` file, README badges, docs footer, release notes.
+ - **Rule**: quote `pyproject.toml`. If asked about a cache that disagrees, report the discrepancy.
- ## Which Wave Updates What
+ ### Planned work
- | Wave | Reads SSOT | Produces Delta | Updates SSOT |
- |------|-----------|----------------|--------------|
- | DISCOVER | `jobs.yaml` | (evidence brief) | `jobs.yaml` + new validated job |
- | DIVERGE | `jobs.yaml`, `vision.md` | `recommendation.md`, `job-analysis.md` | `jobs.yaml` |
- | DISCUSS | `journeys/`, `jobs.yaml`, `vision.md` | `user-stories.md`, `story-map.md`, `outcome-kpis.md` | `journeys/` (extends journey), `jobs.yaml` (if new job from DIVERGE) |
- | DESIGN | `architecture/brief.md`, `journeys/` | `wave-decisions.md` | `architecture/brief.md` + ADRs + `c4-diagrams.md` |
- | DEVOPS | `architecture/brief.md`, `kpi-contracts.yaml` | (infra spec) | `kpi-contracts.yaml` |
- | DISTILL | all above | `acceptance-tests.feature` | (none) |
- | DELIVER | `acceptance-tests.feature` | code | (code is the SSOT) |
+ - **Authoritative**: `BACKLOG.md` at the repo root.
+ - **Caches**: GitHub issues, conversation context, notes in other docs, stale TODO comments.
+ - **Rule**: work that isn't in `BACKLOG.md` is not planned. Don't invent items. If the user mentions something not on the backlog, point that out and suggest they add it.
- ## Old Model (Backward Compatibility)
+ ### Architecture intent
- Features created before SSOT use per-wave subdirectories:
+ - **Authoritative**: `docs/architecture/architecture-design.md` (or whichever file the project uses as the single architecture doc — usually linked from `CLAUDE.md` or `README.md`).
+ - **Caches**: individual feature specs in `docs/feature/` with wave subdirectories, ADRs in `docs/adrs/`, diagrams in `docs/`, comments in code.
+ - **Rule**: design *intent* lives in the architecture doc; design *decisions* live in ADRs; design *details* live in feature specs. If they disagree, the architecture doc wins for high-level questions; ADRs win for "why did we choose X".
- ```
- docs/feature/{id}/ <- OLD MODEL (note: "feature" singular)
- discover/
- diverge/
- discuss/
- design/
- devops/
- distill/
- deliver/
- ```
+ ### Runtime behavior
- **Migration gate** (CRITICAL): If `docs/product/` does not exist but `docs/feature/` has existing features, the project MUST migrate before running new waves. All wave skills enforce this gate. Direct the user to the migration guide: `docs/guides/migrating-to-ssot-model/README.md`.
+ - **Authoritative**: the code.
+ - **Caches**: docs, specs, comments, commit messages.
+ - **Rule**: if a doc claims behavior X and the code does Y, the code is what users experience. Report the discrepancy as a finding.
- **Key difference**: `docs/feature/` (singular, old) vs `docs/features/` (plural, new delta).
+ ### Configuration
- ## Migration Path
+ - **Authoritative**: the config file the runtime actually loads (`pyproject.toml`, `.pre-commit-config.yaml`, `ci.yml`, whichever applies).
+ - **Caches**: docs describing the config, README examples.
+ - **Rule**: quote the real file, including its path.
- Follow the step-by-step guide: `docs/guides/migrating-to-ssot-model/README.md`
+ ### Agent / command definitions
- Summary of the 7 steps:
+ - **Authoritative**: the YAML frontmatter of the agent or command file, and the framework catalog (`framework-catalog.yaml` or equivalent) if the project uses one.
+ - **Caches**: READMEs, marketing docs, generated reference pages.
+ - **Rule**: trust the frontmatter + catalog.
- 1. Create `docs/product/` directory structure
- 2. Extract validated jobs into `jobs.yaml`
- 3. Consolidate journeys from features into `journeys/`
- 4. Create architecture brief from design artifacts
- 5. Extract KPI contracts
- 6. Create vision.md (one-time, ~50 lines)
- 7. Verify YAML syntax, commit
+ ### Git state
- No forced migration. Old and new coexist. New features use SSOT automatically.
+ - **Authoritative**: `git status`, `git log`, `git branch`.
+ - **Caches**: conversation memory, "what I was doing" notes.
+ - **Rule**: run git commands before answering state questions. Never guess.
- ## Schema Versioning
+ ## Conflict resolution hierarchy
- SSOT YAML files include `schema_version: 1` and a `changelog:` section tracking which feature changed what, when. This enables conflict resolution at git merge time.
+ When two sources disagree and it isn't obvious which wins, use this hierarchy from most to least authoritative:
- ## Document Count Comparison
+ 1. The code itself (runtime behavior).
+ 2. The config files that control the runtime.
+ 3. The SSOT file declared by the project (`BACKLOG.md`, `architecture-design.md`, etc.).
+ 4. ADRs (for "why" questions).
+ 5. Feature specs.
+ 6. Generated docs.
+ 7. README.
+ 8. Prose in commit messages.
+ 9. Conversation context and memory.
- Old model: ~26 documents per feature. New model: ~6 delta files per feature + shared SSOT. Result: 77% fewer documents, single source of truth always current.
+ Reporting a conflict is a valuable answer. "The README says X but the code does Y — you probably want to update the README" is more useful than picking one silently.
- ## How to Check Document Model
+ ## How to recognize a stale secondary copy
- To determine which model a project uses:
+ Signals that a doc is out of date:
- 1. Check if `docs/product/` exists -> SSOT model active
- 2. Check if `docs/features/` exists -> new delta files present
- 3. Check if `docs/feature/` exists -> old model features present
- 4. Both can coexist in the same project
+ - It references APIs, commands, or files that no longer exist in the repo.
+ - It claims a version number older than `pyproject.toml`.
+ - Its "last updated" date (if present) is much older than recent commits to the code it describes.
+ - Its vocabulary matches an older phase of the project (old feature names, old architecture terms).
+ - It contradicts a more recent ADR.
- > For the full authoritative SSOT model reference, read `docs/guides/understanding-ssot-model/README.md`.
- > For the migration guide, read `docs/guides/migrating-to-ssot-model/README.md`.
+ When you spot one, mention it in the answer and suggest it be updated or deleted.
+
+ ## Read-before-answer discipline
+
+ Before any concrete answer:
+
+ 1. Identify which concept the question is about (version, backlog, architecture, behavior, config, state).
+ 2. Look up the SSOT for that concept in the map above.
+ 3. Read the authoritative file.
+ 4. Form the answer from that file, with a citation.
+ 5. If you also happen to see a contradicting cache, report it.
+
+ Don't answer from memory. The buddy agent's memory is not an SSOT; the repo is.
+
+ ## Never invent, always cite
+
+ If you don't find the information, say so and suggest where the user might add it. Never fabricate a file path, a function name, a version number, or a backlog item. Fabrication destroys trust; "I couldn't find this" preserves it.
+
+ ## A short example
+
+ User asks: "what version are we on and what's next?"
+
+ Good answer:
+
+ > We're on v2.17.5 (`pyproject.toml:3`). The top three items in `BACKLOG.md` are:
+ > 1. Finish the D-PLUGIN-00b delivery (`BACKLOG.md:12`)
+ > 2. Docker validation matrix refresh (`BACKLOG.md:27`)
+ > 3. CI matrix expansion (`BACKLOG.md:34`)
+ >
+ > Note: the README badge shows v2.17.3 — probably stale, consider updating.
+
+ Bad answer:
+
+ > I think we're on v2.17 something and you're working on the plugin feature.
+
+ The good answer is sourced, cited, and adds a finding. The bad answer is vibes.