How to configure documentation density

Use case 1: I want lean output by default

Situation: You're a solo developer iterating quickly. Token cost matters. You want feature-delta files to include only the essential specs, decisions, and scenarios — no JTBD narrative or persona essays.

Solution:

{
  "rigor": {
    "profile": "lean"
  }
}

Or explicitly:

{
  "documentation": {
    "density": "lean",
    "expansion_prompt": "always-skip"
  }
}

Result:

• Every wave produces feature-delta.md with only [REF] sections (factual content: personas, job statements, specs, decisions, scenarios).
• Optional expansions (JTBD narratives, alternatives considered, migration playbooks) are skipped.
• Each feature-delta file averages ≤60% of legacy token cost.

Next step: If you need more detail on a specific feature, see "Ad-hoc expansion" below.

Use case 2: I want full output for a feature handoff

Situation: You're handing off a complex feature to a teammate. You want comprehensive documentation with all the rationale, design alternatives, and migration guidance inline — no surprises.

Solution:

{
  "documentation": {
    "density": "full"
  }
}

Result:

• Every wave produces feature-delta.md with all sections: [REF] (facts) + [WHY] (rationale) + [HOW] (procedures).
• JTBD narratives, alternatives, and migration playbooks are included inline.
• Your teammate reads the complete story in one file.

Use case 3: I want trigger-scoped suggestions

Situation: You want lean output, with suggestions only when a wave-specific signal indicates that an expansion may help.

Solution:

{
  "documentation": {
    "expansion_prompt": "ask-intelligent"
  }
}

Result:

• Each wave evaluates its documented expansion triggers.
• If no trigger fires, no menu is shown.
• If triggers fire, the menu contains only their suggested expansions.

The older smart value remains accepted for compatibility and currently behaves like the broad ask menu. Existing configurations are not rewritten automatically.

Method 1: Use the --expand flag

When running a wave, pass the --expand flag with a comma-separated list of expansion IDs:

/nw-discuss my-complex-feature --expand jtbd-narrative,alternatives-considered

Result: The wave produces lean base content + the two requested expansions. The feature-delta file gains:

• ## Wave: DISCUSS / [WHY] JTBD narrative
• ## Wave: DISCUSS / [WHY] Alternatives considered

Idempotent: Running expand again on the same feature skips already-present sections (no duplication).

Method 2: Respond to the wave-end prompt

If expansion_prompt: "ask":

/nw-discuss my-complex-feature

At the end of the wave, you see:

Expand any of these?

1. jtbd-narrative       Full Job-to-be-Done analysis with four forces
2. persona-narrative    Extended persona (goals, frustrations, environment)
3. alternatives-considered  Design alternatives weighed and rejected
4. migration-playbook   Procedural notes for migrating existing surfaces

Select (1,2,3,4) or press Enter to skip:

Enter a number to add that expansion (e.g., 1 adds JTBD narrative). Press Enter with no input to skip all. You can select one or more:

Select (1,2,3,4) or press Enter to skip: 1,3

Adds JTBD narrative + alternatives-considered to the same wave's feature-delta.

Finding available expansions

Each wave's feature-delta lists available expansions in the [REF] Expansion catalog section.

grep -A 20 "Expansion catalog" docs/feature/my-feature/feature-delta.md

Available expansion IDs per wave:

• DISCUSS: jtbd-narrative, persona-narrative, alternatives-considered, research-synthesis, etc.
• DESIGN: adr-rationale, alternatives-technical, etc.
• DISTILL: edge-cases-deep-dive, etc.
• DELIVER: retrospective, lessons-learned, etc.

Profile cascade table

What this means:

• Start with rigor: "lean" for solo iteration. Lean density + auto-skip expansions by default.
• Move to rigor: "standard" for team work. Lean density + trigger-scoped expansion suggestions.
• Use rigor: "thorough" for regulated environments. Full density + all expansions inline.

Override: Explicit documentation.density always wins, even if rigor suggests otherwise:

{
  "rigor": {
    "profile": "thorough"
  },
  "documentation": {
    "density": "lean"
  }
}

This combination means: high ceremony (thorough wave validation) but minimal prose (lean output).

Q: I set density: "lean" but the output still has lots of narrative. Why?

A: Check two things:

1. Is expansion_prompt: "always-expand"? If so, all expansions are auto-included even in lean mode.

   # Fix: Change to ask-intelligent or always-skip
   nwave-ai doctor | grep "expansion prompt"

2. Are you running with --expand <ids>? The flag overrides density for that run.

   # You ran: /nw-discuss my-feature --expand jtbd-narrative
   # This adds JTBD narrative on top of lean base.
   # To get pure lean, don't use --expand flag.

Q: My config file doesn't exist. What's the default?

A: Run nwave-ai install again. The first-run prompt will ask for density preference:

Documentation density: lean (experienced developer) / full (first feature)?

Pick one. It's saved and never prompted again (idempotent).

Q: Can I have different density for different features?

A: Not in v3.14. The global config applies to all features. Per-feature overrides are on the roadmap.

Q: What if I'm running in CI (non-interactive)?

A: When there's no terminal (TTY), interactive prompts are skipped. nWave defaults to always-skip behavior for expansions, even if expansion_prompt: "ask" is set. Lean output is still produced. To include specific expansions in CI:

/nw-discuss my-feature --expand jtbd-narrative

The --expand flag works in non-interactive contexts.

Q: My teammate wants full documentation. Should they change the global config or use --expand?

A: Depends on their workflow:

• One-time: Use --expand <ids> for that wave.
• Permanent preference: Change documentation.density in ~/.nwave/global-config.json.
• Team default: Coordinate on a rigor profile in project-level documentation and share the recommended global-config.json template.