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.

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%, 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

/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 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: 466kUpdated 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: 196kUpdated 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: 196kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall