Density Resolution Contract (shared across wave skills)

Density Resolution Contract (shared across wave skills)

This skill is the canonical source for the density-aware behaviour every wave skill must implement. Wave skills inherit it by reference and keep a brief inline summary so phrase-grep contract tests stay green; full detail lives here so the same boilerplate is not duplicated six times.

Provenance: feature lean-wave-documentation — D2 (schema-typed sections), D4 (telemetry instrumented day-one), D6 (first-install pedagogical prompt), D10 (one-line expansion descriptions), D12 (rigor cascade), DDD-5 (density resolver shared utility), DDD-6 (telemetry event lives in DES domain).

Output Tiers (per D2 + D10)

Each wave emits a single feature-delta.md whose headings are typed [REF] (always emitted) or [WHY]/[HOW] (lazy expansions). Tier-1 is the always-on baseline; Tier-2 is the lazily-rendered expansion catalog. The .feature file (DISTILL) and other machine artifacts remain the SSOT for executable content; the wave-delta sections are pointers + structured summaries.

• Tier-1 [REF] — emitted under ## Wave: <NAME> / [REF] <Section> headings on every run. Wave-specific list of [REF] sections lives in each wave skill.
• Tier-2 EXPANSION CATALOG — NOT emitted by default. Rendered only when explicitly requested via --expand <id> (DDD-2), via the broad wave-end menu when expansion_prompt = "ask", or via a trigger-scoped menu when expansion_prompt = "ask-intelligent" and the active wave declares a matching trigger. Each item has a one-line description (per D10) so the menu fits in a single render. Each emitted Tier-2 section is headed ## Wave: <NAME> / [WHY] <Section> or ## Wave: <NAME> / [HOW] <Section>. The catalog itself is wave-specific.

Density resolution (per D12)

Before emitting any Tier-1 section, resolve the active documentation density:

1. Read ~/.nwave/global-config.json. Treat missing/malformed config as empty dict (fall back to defaults).
2. Call resolve_density(global_config) from scripts/shared/density_config.py. The function returns a Density value object with fields mode ("lean" | "full"), expansion_prompt ("ask" | "ask-intelligent" | "always-skip" | "always-expand" | "smart"), and provenance (the cascade branch that produced this result).
3. Branch on density.mode:
   • lean → emit ONLY Tier-1 [REF] sections. Do NOT auto-render Tier-2 items.
   • full → emit Tier-1 [REF] sections PLUS all Tier-2 expansion items rendered under their [WHY] / [HOW] headings. This is auto-expansion (no menu).
4. At wave end, branch on density.expansion_prompt:
   • "ask" → present the expansion menu (Tier-2 catalog with one-line descriptions per D10) and append user-selected items as ## Wave: <NAME> / [WHY|HOW] <Section> headings.
   • "ask-intelligent" → use only triggers explicitly declared by the active wave and present only the matching Tier-2 items. If the wave has no declared triggers, or none fires, present no menu; never infer or invent a trigger.
   • "always-skip" → no menu, no extra sections (idempotent re-runs, CI mode).
   • "always-expand" → equivalent to mode = "full" for this run; auto-render every Tier-2 item.
   • "smart" → out of scope for v1 (per OQ-3); treat as "ask" until heuristic is empirically tuned.

The only current trigger catalog is nWave/skills/nw-discuss/SKILL.md, under ### Trigger detection (ask-intelligent mode, per Decision 4). It is canonical for DISCUSS only; no other wave currently declares triggers. Consequently, ask-intelligent means no menu in those waves until their own skill declares a trigger catalog. This explicit cross-reference resolves the navigability gap tracked by public issue #95 without moving or broadening the catalog.

The resolver itself encodes the D12 cascade independently per key: a configured value overrides its own dimension; otherwise the rigor.profile mapping applies (lean→lean+always-skip, standard→lean+ask-intelligent, thorough→full+always-expand, exhaustive→full+always-expand, custom→lean+ask-intelligent), with hard default lean+ask-intelligent. Wave skills MUST NOT replicate the cascade locally — call resolve_density(global_config) and trust its output.

Section heading prefix convention (per D2): every emitted section starts with ## Wave: <NAME> / [REF] <Section> for Tier-1; ## Wave: <NAME> / [WHY] <Section> or ## Wave: <NAME> / [HOW] <Section> for Tier-2. Validator scripts/validation/validate_feature_delta.py enforces the regex ^## Wave: \w+ / \[(REF|WHY|HOW)\] .+$ on every wave heading.

Ad-hoc override — user request mid-session

Even when density.mode = "lean" and density.expansion_prompt = "always-skip", the user may ask DURING the wave session for specific expansions:

• "expand jtbd" / "expand jtbd-narrative" / "more on jtbd"