Skip to content

nWave-ai/nWave / nWave/skills/nw-document

nw-document

Verified

Creates evidence-based documentation following DIVIO/Diataxis principles. Use when writing tutorials, how-to guides, reference docs, or explanations.

FileKindSize
SKILL.mdskill md5.8 KB
---
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

```bash
/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%, every diagram passes R1-R12 of `nw-diagram`. 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 within the review-round limit the role bundle prints (nwdes prompt). When a finding is still open at the limit, a finding still open at the limit returns to its owner and is reported open; the limit is never an approval, and unresolved findings go to the user.
3. **REJECTED / RESTRUCTURE_REQUIRED**: Escalate immediately — restart|adjust scope|accept with issues|cancel.

## Examples

### Example 1: Tutorial with auto-depth
```bash
/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
```bash
/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
```bash
/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 within the review-round limit the role bundle prints (nwdes prompt)
- [ ] Documentation follows DIVIO template with >=80% type purity
- [ ] Doc review: APPROVED within the review-round limit the role bundle prints (nwdes prompt)
- [ ] 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`
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall