nw-buddy-wave-knowledge · diff
git:20260407.2d944b1 to git:20260410.37670e3
103 added, 68 removed. Audit A to A.
---
name: nw-buddy-wave-knowledge
- description: How the 7-wave methodology works — wave graph, entry points, skip conditions, and handoff chain. For the buddy agent to explain methodology to users.
- user-invocable: false
- disable-model-invocation: true
+ description: Wave methodology knowledge for the buddy agent — what each wave does, its inputs and outputs, and how to route questions.
---
# Wave Methodology Knowledge
- ## The 7-Wave Graph
+ The nWave methodology organizes work into a canonical sequence of **waves**. Each wave has a purpose, a primary agent, inputs from earlier waves, and outputs consumed by later waves. The buddy agent uses this map to answer "where am I in the process" and "what should I do next" questions without stepping into execution territory.
- nWave is a graph, not a linear pipeline. Not every feature runs all 7 waves.
+ ## The canonical wave sequence
```
- DISCOVER -> DIVERGE -> DISCUSS -> DESIGN -> DEVOPS -> DISTILL -> DELIVER
+ DISCOVER -> DISCUSS -> SPIKE(opt) -> DESIGN -> DEVOPS -> DISTILL -> DELIVER
```
- **Invariant**: Every feature ends with DISTILL -> DELIVER. No exceptions.
+ Each wave has a slash command (`/nw-<wave>`) and a primary agent. Waves run top-to-bottom. Skipping waves is a smell; going back to revise an earlier wave is normal and expected. SPIKE is optional — include it when validating a new mechanism, performance requirement, or external integration.
- ## Wave Purposes
+ ## Wave-by-wave reference
- | Wave | Agent | Purpose | Produces |
- |------|-------|---------|----------|
- | DISCOVER | product-discoverer (Scout) | Validate the problem exists with real customer evidence | Validated jobs, opportunity tree, lean canvas |
- | DIVERGE | diverger (Flux) | Generate and evaluate multiple solution approaches | Recommendation, JTBD analysis, taste evaluation |
- | DISCUSS | product-owner (Luna) | Define user stories, journeys, acceptance criteria | User stories, journey schemas, requirements |
- | DESIGN | system-designer, ddd-architect, solution-architect | Route to the right architect — system (scalability), domain (DDD), or application (components). All write to shared architecture brief. | Architecture brief, C4 diagrams, domain models |
- | DEVOPS | platform-architect | CI/CD, infrastructure, observability, KPI contracts | Platform design, KPI contracts |
- | DISTILL | acceptance-designer | Create executable acceptance tests (Given-When-Then) | Feature files, step definitions |
- | DELIVER | software-crafter | Implement via Outside-In TDD (roadmap -> execute -> finalize) | Working code, passing tests |
+ ### 1. DISCOVER
- ## Entry Points
+ - **Purpose**: validate that an opportunity exists and is worth pursuing.
+ - **Primary agent**: product-discoverer.
+ - **Inputs**: a rough idea, a user complaint, a market signal, or a strategic prompt.
+ - **Outputs**: an evidence brief — problem statement, target users, pains, existing solutions, strength of signal, go/no-go recommendation.
+ - **Typical artifacts**: `docs/discover/<opportunity>-brief.md`, user interview notes, competitive scans.
+ - **Common questions**: "is this worth doing?", "who has this problem?", "what's the evidence?"
- Choose starting wave based on what you already know:
+ ### 2. DISCUSS
- | Situation | Start At | Example |
- |-----------|----------|---------|
- | New product, no context | DISCOVER | "Build a payment processor" |
- | Feature with multiple approaches | DIVERGE | "Add rate limiting -- token bucket or sliding window?" |
- | Feature on known journey | DISCUSS | "Add 2FA to login" |
- | Technical story, scope clear | DESIGN | "Refactor auth module" |
- | Bug fix, cause known | DISTILL | "Auth token expires too early" |
- | Bug fix, cause unknown | DISCOVER | "Auth randomly fails" |
- | Infrastructure change | DEVOPS | "Add Redis caching layer" |
+ - **Purpose**: turn a validated opportunity into user stories with acceptance criteria.
+ - **Primary agent**: product-owner.
+ - **Inputs**: DISCOVER output — validated problem and target users.
+ - **Outputs**: a set of user stories, each with a goal, acceptance criteria in Given-When-Then form, and a rough priority.
+ - **Typical artifacts**: `docs/discuss/<feature>-stories.md`, a backlog update.
+ - **Common questions**: "what does 'done' look like for this feature?", "what are the user stories?"
- ## Skip Conditions
+ ### 3. SPIKE (optional)
- Each wave can be skipped only if ALL items in its checklist are true.
+ - **Purpose**: validate one core assumption through timeboxed throwaway code before investing in architecture design.
+ - **Primary agent**: software-crafter.
+ - **Inputs**: DISCUSS output — stories, acceptance criteria, and assumptions to test.
+ - **Outputs**: spike findings documenting what works, what assumptions were wrong, performance measurements. Code is discarded.
+ - **Typical artifacts**: `docs/feature/<name>/spike/findings.md`, throwaway code (not committed).
+ - **Common questions**: "will this mechanism work?", "can we hit the performance budget?", "does the third-party API behave as expected?"
+ - **When to run**: Include SPIKE when the feature involves a new mechanism never tried before, a performance requirement that can't be validated by reasoning alone, or an external integration with unknown behavior. Skip for pure refactoring, bug fixes, or features < 1 day.
+ - **Duration**: max 1 hour, timeboxed.
- ### DISCOVER skip
- - `docs/product/jobs.yaml` has a validated job matching this feature
- - The job has `status: validated` and `validated_by` with a real reference
+ ### 4. DESIGN
- ### DIVERGE skip
- - Direction is clear (backlog specifies approach)
- - No competing solutions need evaluation
- - `recommendation.md` already exists or direction is self-evident
+ - **Purpose**: propose the solution architecture — component boundaries, key abstractions, major trade-offs.
+ - **Primary agent**: solution-architect.
+ - **Inputs**: DISCUSS output — stories and acceptance criteria. SPIKE findings (if spike was run) — validated assumptions and performance constraints.
+ - **Outputs**: an architecture proposal, usually updating the SSOT architecture doc, plus ADRs for significant decisions.
+ - **Typical artifacts**: `docs/architecture/architecture-design.md` updates, `docs/adrs/ADR-NNN-<title>.md`, diagrams.
+ - **Common questions**: "how will this be built?", "what are the components?", "what are the boundaries?"
- ### DISCUSS skip
- - `docs/product/journeys/{name}.yaml` covers this behavior
- - Journey changelog shows recent update (not stale)
- - Existing user stories cover this feature's scope
+ ### 5. DEVOPS
- ### DESIGN skip
- - `docs/product/architecture/brief.md` covers components touched
- - No new component boundaries or ADRs needed
- - "For Acceptance Designer" section lists the driving port
+ - **Purpose**: plan the infrastructure, CI/CD, and deployment needed to run what DESIGN proposed.
+ - **Primary agent**: platform-architect.
+ - **Inputs**: DESIGN output.
+ - **Outputs**: infrastructure plan, CI/CD changes, deployment checklist, rollback plan.
+ - **Typical artifacts**: updated CI workflow files, IaC changes, runbooks.
+ - **Common questions**: "how do we ship this?", "what does CI need?", "what's the rollback plan?"
- ### DEVOPS skip
- - `docs/product/kpi-contracts.yaml` has a contract for this feature
- - No new infrastructure or deployment changes needed
+ ### 6. DISTILL
- ## Handoff Chain
+ - **Purpose**: translate stories and acceptance criteria into executable BDD test scenarios — the specification the crafter will implement against.
+ - **Primary agent**: acceptance-designer.
+ - **Inputs**: DISCUSS stories and DESIGN architecture.
+ - **Outputs**: `tests/acceptance/` files with Given-When-Then scenarios, tagged with `@skip` initially, plus a roadmap of delivery steps.
+ - **Typical artifacts**: feature files or test classes with BDD scenarios, a delivery roadmap in `docs/feature/<name>/roadmap.md`.
+ - **Common questions**: "what are the test scenarios?", "what's the delivery plan?"
- Each wave reads SSOT first, then prior wave delta:
+ ### 7. DELIVER
- ```
- DISCOVER -> DIVERGE reads jobs.yaml + vision.md
- DIVERGE -> DISCUSS reads recommendation.md + job-analysis.md + journeys/ + jobs.yaml + vision.md
- DISCUSS -> DESIGN reads architecture/brief.md + journeys/*.yaml + user-stories.md
- DESIGN -> DEVOPS reads architecture/brief.md + kpi-contracts.yaml + outcome-kpis.md
- DEVOPS -> DISTILL reads all 3 SSOT dimensions (journeys + architecture + kpi-contracts)
- DISTILL -> DELIVER reads acceptance-tests.feature
- ```
+ - **Purpose**: implement the feature using Outside-In TDD, step by step, until all DISTILL scenarios pass.
+ - **Primary agent**: software-crafter.
+ - **Inputs**: DISTILL output — scenarios and roadmap.
+ - **Outputs**: working, tested, committed code.
+ - **Typical artifacts**: commits following the TDD 5-phase cycle (PREPARE -> RED_ACCEPTANCE -> RED_UNIT -> GREEN -> COMMIT), updated tests, updated source files.
+ - **Common questions**: "is this feature done?", "what step are we on?", "is the test suite green?"
- ## Key Commands
+ ## Cross-wave agents
- | Command | Wave | Quick Description |
- |---------|------|-------------------|
- | `/nw-new` | routing | Guided wizard -- asks what you're building, recommends starting wave |
- | `/nw-continue` | routing | Detects progress, resumes at next wave |
- | `/nw-fast-forward` | routing | Runs remaining waves without stopping between them |
+ Some agents operate across waves:
- ## How to Recommend the Next Wave
+ - **researcher** — gathers evidence for any wave that needs it.
+ - **troubleshooter** — diagnoses problems in existing code or processes.
+ - **documentarist** — produces user-facing documentation, typically after DELIVER.
+ - **visual-architect** — produces diagrams to support DESIGN.
- When a user asks "what should I do next?", walk through the Entry Points table above — match their situation to the starting wave. Then check Skip Conditions for any waves between their entry point and DISTILL. Skip what's already covered by SSOT.
+ Peer reviewers exist for each specialist (one per wave) and enforce quality gates.
- After DISTILL, always DELIVER.
+ ## Routing questions to the right wave
- > For the full authoritative wave routing reference, read `docs/guides/wave-routing-and-entry-points/README.md`.
+ When a user asks something, the buddy identifies which wave owns the question and answers from that wave's artifacts. Examples:
+
+ | Question | Wave | Where to read |
+ |---|---|---|
+ | "Is this idea any good?" | DISCOVER | discover briefs |
+ | "What are the user stories?" | DISCUSS | story docs / backlog |
+ | "How will the module be shaped?" | DESIGN | architecture doc, ADRs |
+ | "What's the CI plan?" | DEVOPS | CI workflows, runbooks |
+ | "What are the test scenarios?" | DISTILL | feature files, roadmap |
+ | "What step are we on?" | DELIVER | commits, test suite, roadmap |
+
+ If the user's question spans multiple waves (e.g., "what's this feature and how does it work?"), answer with contributions from each relevant wave, in order.
+
+ ## Recognizing which wave the user is in
+
+ Signals:
+
+ - **DISCOVER**: user is asking about opportunity, not code. Words like "should we", "is there demand".
+ - **DISCUSS**: user is talking about stories, acceptance criteria, user needs.
+ - **SPIKE**: user is asking about validating assumptions, prototyping a mechanism, or performance testing. Words like "prove it works", "test this idea", "spike".
+ - **DESIGN**: user is asking about components, layers, boundaries, trade-offs.
+ - **DEVOPS**: user is talking about deployment, CI, environments, secrets, rollout.
+ - **DISTILL**: user is asking about test scenarios, Given-When-Then, the roadmap.
+ - **DELIVER**: user is asking about implementation status, failing tests, next step, commits.
+
+ If unsure, ask.
+
+ ## What the buddy does NOT do
+
+ - **Does not run the crafter.** The buddy is read-only guidance. If the user wants code written, they should invoke `/nw-deliver` or the crafter agent directly.
+ - **Does not skip waves.** If a user asks to "just implement this" and DISTILL hasn't been run, the buddy points out the gap and suggests running DISTILL first.
+ - **Does not invent artifacts.** If a DESIGN doc doesn't exist, the buddy says so — it doesn't make one up.
+ - **Does not write acceptance tests on the fly.** That's DISTILL's job.
+ - **Does not change the wave order.** The sequence exists because each wave depends on the previous.
+
+ ## Rule of thumb
+
+ The buddy's mental model is always: *"What wave is this question in, which files hold the answer, and what are the gaps?"* Answer from those files, cite them, and flag gaps as findings.