nw-design

NW-DESIGN: Architecture Design

Wave: DESIGN (wave 3 of 6) | Agents: Morgan (nw-solution-architect), nw-system-designer, nw-ddd-architect | Command: *design-architecture

Overview

Execute DESIGN wave through discovery-driven architecture design. The command starts with two interactive decisions:

1. Design Scope — routes to the right architect: system-level (@nw-system-designer), domain-level (@nw-ddd-architect), application-level (@nw-solution-architect), or full stack (all three in sequence).
2. Interaction Mode — guide (architect asks questions, you decide together) or propose (architect reads requirements, presents 2-3 options with trade-offs).

All architects write to docs/product/architecture/brief.md (SSOT), each in its own section. Analyzes existing codebase, evaluates open-source alternatives, produces C4 diagrams (Mermaid) as mandatory output.

Output Tiers (per D2)

Provenance: feature lean-wave-documentation — D2 (schema-typed sections), D10 (one-line expansion descriptions). 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: DESIGN / [REF] <Section> headings:

• DDD list — D-numbered design decisions with verdicts and one-line rationale
• Component decomposition — table of components with paths and change types
• Driving ports — inbound surfaces (CLI, skill, HTTP) named per the C4 contract
• Driven ports + adapters — outbound side-effects with adapter mapping
• Technology choices — pinned languages/frameworks/runtime versions
• Decisions table — DDD-N row per locked decision (no rationale prose)
• Reuse Analysis table — every overlapping component classified EXTEND or CREATE NEW
• Open questions — items deliberately deferred to DISTILL/DELIVER

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

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

| Expansion ID | Tier label | One-line description | |---|---|---| | trade-off-analysis | [WHY] | Quality-attribute trade-off matrix with prioritization rationale | | rejected-alternatives | [WHY] | Architectures weighed and rejected with one-paragraph reason per option | | c4-narrative | [HOW] | Long-form C4 walkthrough: System Context → Container → Component prose | | evolution-scenarios | [WHY] | Hypothetical future stress vectors and how the design absorbs them | | paradigm-rationale | [WHY] | Why FP/OOP was selected; comparison vs the alternative for this domain | | reuse-analysis-deep-dive | [WHY] | Per-row justification for every EXTEND vs CREATE NEW decision in the Reuse table | | c4-component-diagrams | [HOW] | Component-level C4 diagrams for complex subsystems (Mermaid) | | 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" | "always-skip" | "always-expand" | "smart") per the D12 cascade (resolver-internal, DDD-5 — do NOT replicate locally). Branch on density.mode for what to emit; branch on density.expansion_prompt at wave end for menu behaviour. Full cascade detail, branch semantics, ad-hoc override workflow: nWave/skills/nw-density-resolution-contract/SKILL.md.

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": "DESIGN". Use helper scripts/shared/telemetry.py:write_density_event(...) — do NOT write JSONL directly.

Wave-specific signal: DEVOPS/DISTILL consuming a lean DESIGN feature-delta — downstream --expand requests for trade-off or evolution scenarios indicate the [REF] baseline was insufficient. Full emission rules: nWave/skills/nw-density-resolution-contract/SKILL.md.

Prior Wave Consultation

Before beginning DESIGN work, read SSOT and prior wave artifacts in this order:

1. Read SSOT architecture (if docs/product/ exists) — read docs/product/architecture/brief.md (extend, not recreate), docs/product/architecture/adr-*.md (existing decisions), docs/product/journeys/{name}.yaml (journey schema for port identification). Gate: all existing files read or confirmed missing.
2. Read DISCUSS artifacts (primary input) — read from docs/feature/{feature-id}/discuss/: wave-decisions.md (decision summary), user-stories.md (scope, requirements, acceptance criteria), story-map.md (walking skeleton and release slicing), outcome-kpis.md (quality attributes). Gate: all four files read or confirmed missing.
3. Read SPIKE findings (if spike was run) — read from docs/feature/{feature-id}/spike/: findings.md (validated assumptions, performance measurements, what didn't work). This informs your architecture constraints. Gate: file read if present, marked as not found if absent.
4. Output confirmation checklist — after reading, output ✓ {file} for each read, ⊘ {file} (not found) for each missing. Gate: checklist produced before any architecture work begins.
5. Check for contradictions — identify any DESIGN decisions that would contradict DISCUSS requirements or SPIKE findings. Flag contradictions and resolve with user before proceeding. Example: DISCUSS requires "real-time updates" but DESIGN chooses batch processing; or SPIKE found performance budget can't be met. Gate: zero unresolved contradictions.
6. Migration gate check — if docs/product/ does not exist but docs/feature/ has existing features, STOP. Guide the user to docs/guides/migrating-to-ssot-model/README.md. If greenfield, proceed — DESIGN will bootstrap docs/product/architecture/. Gate: migration status confirmed.

Note: DISCOVER evidence is already synthesized into DISCUSS — read DISCOVER only if wave-decisions.md flags something architecturally significant.

Document Update (Back-Propagation)

When DESIGN decisions change assumptions from prior waves:

1. Document the change — add a ## Changed Assumptions section at the end of the affected DESIGN artifact. Gate: section present in artifact.
2. Reference the original — quote the original assumption from the prior-wave document, with file path. Gate: original quoted verbatim with source.
3. State the new assumption — write the replacement assumption and its rationale. Gate: new assumption and rationale present.
4. Propagate upstream if needed — if architecture constraints require changes to user stories or acceptance criteria, write them to docs/feature/{feature-id}/design/upstream-changes.md for the product owner to review. Gate: upstream-changes.md created if any story/criteria changes needed.

Discovery Flow

Architecture decisions are driven by quality attributes, not pattern shopping. Execute these steps in order:

1. Understand the Problem — review JTBD artifacts from DISCUSS. Ask: What are we building? For whom? Which quality attributes matter most? (scalability|maintainability|testability|time-to-market|fault tolerance|auditability). Gate: quality attribute priorities ranked.
2. Understand Constraints — ask: Team size/experience? Timeline? Existing systems to integrate? Regulatory requirements? Operational maturity (CI/CD, monitoring)? Gate: constraints list documented.
3. Map Team Structure (Conway's Law) — ask: How m