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 ATDD 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 regression — DESIGN consumes lean DISCUSS feature-delta.md and produces no --expand invocation". ask-intelligent emission rules: one expand event per scoped-menu acceptance; one skip event for no-trigger silent-lean; one skip event for triggers fired but user declined. Full emission rules + per-mode patterns: nWave/skills/nw-density-resolution-contract/SKILL.md.

Interactive Decision Points

Decision 1: Feature Type

Question: What type of feature is this? Options:

1. User-facing -- UI/UX functionality visible to end users
2. Backend -- APIs, services, data processing
3. Infrastructure -- DevOps, CI/CD, tooling
4. Cross-cutting -- Spans multiple layers (auth, logging, etc.)
5. Other -- user provides custom input

Decision 2: Walking Skeleton

Question: Should we start with a walking skeleton? Options:

1. Yes -- recommended for greenfield projects
2. Depends -- brownfield; Luna evaluates existing structure first
3. No -- feature is isolated enough to skip

Decision 3: UX Research Depth

Question: Priority for UX research depth? Options:

1. Lightweight -- quick journey map, focus on happy path
2. Comprehensive -- full experience mapping with emotional arcs
3. Deep-dive -- extensive user research, multiple personas, edge cases

Decision 4: JTBD Analysis

Question: Include Jobs-to-be-Done analysis? Options:

1. Yes -- mandatory by default. Every user-facing story must trace to a job_id in docs/product/jobs.yaml. Stories without job traceability fail Definition of Ready.
2. No (infrastructure-only escape valve) -- only permitted when the feature is a pure internal change (e.g. rename internal module, refactor build script) with no user-visible behavior. Requires job_id: infrastructure-only AND a infrastructure_rationale field on every story explaining why no user job applies. Reviewer will reject this option for any feature that touches user-facing surfaces.

Default: 1 (Yes). Rationale: STANDING rule "Tech-surface vs value-out