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 context-aware (smart)

Situation: You want nWave to decide per feature. Simple bugfixes get lean output. Complex architectural changes get full output. Token-efficient but complete where it matters.

Solution:

{
  "documentation": {
    "expansion_prompt": "smart"
  }
}

Note: This is experimental in v3.14. Feedback welcome.

Result:

• Wave agents analyze the feature complexity and choose density automatically.
• Small fixes lean toward [REF] only.
• Large features lean toward [REF] + recommended [WHY] sections.

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 + interactive expansion menu.
• 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 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.