nw-discuss

# NW-DISCUSS: Jobs-to-be-Done Analysis, UX Journey Design, and Requirements Gathering

**Wave**: DISCUSS (wave 2 of 6) | **Agent**: Luna (nw-product-owner) | **Command**: `/nw-discuss`

## Overview

Execute DISCUSS wave through Luna's integrated workflow: JTBD analysis|UX journey discovery|emotional arc design|shared artifact tracking|requirements gathering|user story creation|acceptance criteria definition. Luna uncovers jobs users accomplish, maps to journeys and requirements, handles complete lifecycle from user motivations through DoR-validated stories ready for DESIGN. Establishes the acceptance-test foundation.

For greenfield projects (no src/ code, no docs/feature/ history), Luna proposes Walking Skeleton as Feature 0.

## Output Tiers (per D2)

Provenance: feature `lean-wave-documentation` — D2 (schema-typed sections), D10 (one-line expansion descriptions), DDD-7 (DISCUSS pilot wave), D6 (install-time pedagogical prompt). Tier-1 [REF] sections (always emitted) + Tier-2 EXPANSION CATALOG items (lazy, on-demand) are the two output bands. Full contract: `nWave/skills/nw-density-resolution-contract/SKILL.md`.

### Tier-1 [REF] — always emitted

Under `## Wave: DISCUSS / [REF] <Section>` headings:

- Persona ID — one-line user identifier mapped to the journey
- JTBD one-liner — single-sentence Job-to-be-Done statement
- Locked decisions — D-numbered design decisions with verdicts
- User stories with elevator pitches — every story has Before/After/Decision-enabled triplet
- Acceptance criteria (ACs) — testable, embedded per story
- Definition of Done (DoD) — 9-item checklist
- Out-of-scope — explicit non-goals
- WS strategy — A/B/C/D per Mandate 5
- Driving ports — inbound surfaces (CLI, skill, HTTP)
- Pre-requisites — dependencies on prior waves or features

### Tier-2 EXPANSION CATALOG — lazy, on-demand (per D10)

Rendered under `## Wave: DISCUSS / [WHY|HOW] <Section>` only when requested via `--expand <id>` (DDD-2), the wave-end menu (`expansion_prompt = "ask"` or `"ask-intelligent"`), `mode = "full"` auto-expansion, or an ad-hoc user request mid-session.

| Expansion ID | Tier label | One-line description |
|---|---|---|
| `jtbd-narrative` | [WHY] | Full JTBD analysis: job dimensions (functional/emotional/social), four forces, opportunity scores |
| `persona-narrative` | [WHY] | Extended persona: goals, frustrations, mental model, vocabulary glossary |
| `alternatives-considered` | [WHY] | Decision rationale: alternatives weighed and rejected per locked decision |
| `migration-playbook` | [HOW] | Step-by-step migration guide for users on a prior version |
| `journey-deep-dive` | [HOW] | Full UX journey: emotional arc, shared artifacts registry, error-path map |
| `gherkin-scenarios` | [HOW] | Generated Gherkin scenarios covering happy path and key error paths |
| `reviewer-findings-trace` | [WHY] | R1-R10 reviewer findings chain with verdicts and how each landed in D1-D10 |
| `expansion-catalog-rationale` | [WHY] | Why this set of expansions, why these defaults, why D10 enforces one-line descriptions |

## Density resolution (per D12)

Call `resolve_density(global_config)` from `scripts/shared/density_config.py` after reading `~/.nwave/global-config.json` (missing/malformed = empty dict). Returns `mode` (`"lean"` | `"full"`) + `expansion_prompt` (`"ask"` | `"ask-intelligent"` | `"always-skip"` | `"always-expand"` | `"smart"`) per the D12 cascade (resolver-internal, DDD-5 — do NOT replicate locally). DISCUSS hard default is `lean`+`ask-intelligent` per Decision 4 (2026-04-28). Branch on `density.mode` (lean = Tier-1 only; full = Tier-1 + all Tier-2) and at wave end on `density.expansion_prompt`. Full cascade detail, branch semantics, ad-hoc override workflow: `nWave/skills/nw-density-resolution-contract/SKILL.md`.

### Trigger detection (`ask-intelligent` mode, per Decision 4)

DISCUSS-specific extension on top of the shared contract. When `expansion_prompt = "ask-intelligent"`, evaluate ALL triggers below against the wave artifacts produced so far. Each trigger that fires contributes its suggested expansion to a scoped menu. If NO trigger fires, emit no menu — strict lean output.

| Trigger | Detection criterion | Suggested expansion |
|---------|--------------------|--------------------|
| AC ambiguity | ≥2 user stories share an AC where reasonable readers could disagree on the outcome | `gherkin-scenarios` |
| Cross-context complexity | Feature touches ≥3 bounded contexts (per DDD glossary) OR ≥3 distinct technologies | `alternatives-considered` |
| Multi-stakeholder need | ≥3 distinct personas referenced across the user stories | `persona-narrative` |
| Compliance / regulatory | ACs reference regulatory terms (GDPR, HIPAA, SOX, audit, retention, encryption, PII, data residency) | `migration-playbook` (data migration) OR `journey-deep-dive` (user-facing) |
| WS strategy = D | Walking Skeleton strategy is "Configurable" (env-switching) | `alternatives-considered` |

Menu when 1+ trigger fires: `Suggested expansions for this feature (triggered by: {trigger names}): - {id}: {description} ... Apply? [Y/n/all/none/custom]`. Do NOT show the generic 8-item Tier-2 catalog in `ask-intelligent` mode — only triggered items. Ad-hoc override path ("expand <X>") still works for any catalog item. Telemetry: one event per scoped-menu choice; when NO trigger fires, one `choice = "skip"` event with `expansion_id = "*"` records the silent-lean opportunity.

## Telemetry (per D4 + DDD-6)

Every expansion choice emits a `DocumentationDensityEvent` (dataclass at `src/des/domain/telemetry/documentation_density_event.py`) via `event.to_audit_event()` → `JsonlAuditLogWriter().log_event(...)`. Schema fields per D4: `feature_id`, `wave`, `expansion_id`, `choice`, `timestamp`. For this wave the schema declares `"wave": "DISCUSS"`. Use helper `scripts/shared/telemetry.py:write_density_event(...)` — do NOT write JSONL directly.

Wave-specific signal: feeds DDD-7 pilot success metric (4) — "downstream agent