/nw-document

name: nw-document
description: "Creates evidence-based documentation following DIVIO/Diataxis principles. Use when writing tutorials, how-to guides, reference docs, or explanations."
user-invocable: true
argument-hint: '[topic/component] - Optional: --type=[tutorial|howto|reference|explanation] --research-depth=[overview|detailed|comprehensive|deep-dive]'

NW-DOCUMENT: DIVIO Documentation Creation

**Wave**: CROSS_WAVE | **Agent**: Orchestrator (self) **Agents**: Nova (nw-researcher)|Scholar (nw-researcher-reviewer)|Quill (nw-documentarist)|nw-documentarist-reviewer

Overview

Create evidence-based, DIVIO-compliant documentation by orchestrating research and writing phases with peer review at each gate. Cross-wave capability for any nWave phase.

Context Files Required

• .nwave/trusted-source-domains.yaml — Embed inline in researcher prompt
• ~/.claude/agents/nw/nw-researcher.md — Extract research methodology
• ~/.claude/agents/nw/nw-documentarist.md — Extract DIVIO framework and templates

Command Syntax

/nw-document [topic] [--type=tutorial|howto|reference|explanation] [--research-depth=overview|detailed|comprehensive|deep-dive]

If `--type` omitted, ask user. If `--research-depth` omitted, auto-select: tutorial->overview|howto->detailed|reference->comprehensive|explanation->deep-dive.

Orchestration Phases

Sub-agents have no Skill tool access. Embed all domain knowledge inline in each Task prompt. Read from agent files and config at orchestration time.

Phase 1: Research           @nw-researcher
Phase 1.5: Research Review  @nw-researcher-reviewer
Phase 2: Documentation      @nw-documentarist
Phase 2.5: Doc Review       @nw-documentarist-reviewer
Phase 3: Handoff

Phase 0: Pre-Flight

1. Validate topic non-empty, type/depth valid if provided 2. If type not specified, present DIVIO selection: TUTORIAL ("Teach me")|HOW-TO ("Help me do X")|REFERENCE ("What is X?")|EXPLANATION ("Why is X?") 3. Determine output: `docs/{tutorials|howto|reference|explanation}/{topic-kebab-case}.md` 4. Read and cache: .nwave/trusted-source-domains.yaml|nw-researcher.md|nw-documentarist.md

Phase 1: Research (@nw-researcher)

Invoke via Task tool. Prompt includes: topic|doc type|research depth|complete .nwave/trusted-source-domains.yaml (inline)|type-specific research focus (from nw-researcher.md)|quality gates: trusted sources only, 3+ sources/claim, citation coverage >95%, source reputation >=0.80. Output: `docs/research/{topic-kebab-case}-for-{type}-doc.md`

Phase 1.5: Research Review (@nw-researcher-reviewer)

Prompt includes: research artifact path|review focus (source verification|bias detection|evidence quality|cross-reference|doc readiness)|quality gates (same as Phase 1)|output: append YAML review metadata. Verdicts: APPROVED|NEEDS_REVISION|REJECTED

Phase 2: Documentation (@nw-documentarist)

Prompt includes: topic|type|research path|DIVIO framework principles (from nw-documentarist.md)|type-specific validation rules + template|collapse detection anti-patterns|quality gates: type purity >=80%, Flesch 70-80, zero spelling errors, zero broken links, style >=95%. Output: doc file + .validation.yaml

Phase 2.5: Documentation Review (@nw-documentarist-reviewer)

Prompt includes: doc artifact path|review focus (classification accuracy|validation completeness|collapse detection|recommendation quality|scores|verdict)|quality gates (same as Phase 2)|output: append YAML review metadata. Verdicts: APPROVED|NEEDS_REVISION|RESTRUCTURE_REQUIRED

Phase 3: Handoff

Verify all deliverables exist and both reviews APPROVED. Present: research path|doc path|validation path|quality gate results|review outcomes and iteration count.

Review Iteration Protocol

Applies to both review gates (Phase 1.5 and 2.5): 1. **APPROVED**: Proceed to next phase 2. **NEEDS_REVISION**: Extract critiques, re-invoke producer with feedback, re-invoke reviewer. Max 2 cycles. Escalate to user after 2 failures. 3. **REJECTED / RESTRUCTURE_REQUIRED**: Escalate immediately — restart|adjust scope|accept with issues|cancel.

Examples

Example 1: Tutorial with auto-depth

/nw-document "Getting Started with nWave" --type=tutorial

Orchestrator auto-selects overview depth, invokes researcher, reviews, invokes documentarist, reviews, outputs to `docs/tutorials/getting-started-with-nwave.md`.

Example 2: Explanation with explicit depth

/nw-document "Why nWave Uses Hexagonal Architecture" --type=explanation --research-depth=deep-dive

Full 4-phase pipeline with deep-dive research. Output to `docs/explanation/`.

Example 3: Interactive type selection

/nw-document "Mikado Method Integration"

Orchestrator prompts user to select DIVIO type before proceeding.

Success Criteria

• [ ] Research created with trusted sources and cross-references
• [ ] Research review: APPROVED (max 2 cycles)
• [ ] Documentation follows DIVIO template with >=80% type purity
• [ ] Doc review: APPROVED (max 2 cycles)
• [ ] All deliverables exist: research|documentation|validation report
• [ ] No collapse anti-patterns detected

Error Handling

• Insufficient sources: continue with gaps|expand scope|cancel
• Review iteration limit exceeded: escalate with persistent issues
• Collapse detected: split into separate docs|revise scope|accept

Next Wave

**Handoff To**: Invoking workflow **Deliverables**:

• Research: `docs/research/{topic}-for-{type}-doc.md`
• Documentation: `docs/{type-dir}/{topic-kebab-case}.md`
• Validation: `docs/{type-dir}/{topic-kebab-case}.md.validation.yaml`