ring:reviewing-docs
Reviewing end-user and product documentation quality across voice/tone, structure, completeness, clarity, and technical accuracy; flags issues with prioritized findings and a pass/needs-revision verdict. Use when reviewing draft docs, running a pre-publication check, auditing existing docs, or enforcing style-guide compliance. Skip when writing new docs, or checking voice only (use ring:applying-voice-and-tone).
What this skill does
# Documentation Review Process
## When to use
- Reviewing draft documentation
- Pre-publication quality check
- Documentation audit
- Ensuring style guide compliance
## Skip when
- Writing new documentation → dispatch the guide-writer or api-writer agent
- Only checking voice → use ring:applying-voice-and-tone
## Sequence
**Runs after:** guide-writer, api-writer (agents)
## Related
**Complementary:** ring:applying-voice-and-tone, ring:structuring-documentation
Review documentation systematically across multiple dimensions. A thorough review catches issues before they reach users.
## Review Dimensions
1. **Voice and Tone** – Does it sound right?
2. **Structure** – Is it organized effectively?
3. **Completeness** – Is everything covered?
4. **Clarity** – Is it easy to understand?
5. **Technical Accuracy** – Is it correct?
---
## Voice and Tone Review
| Check | Flag If |
|-------|---------|
| Second person | "Users can..." instead of "You can..." |
| Present tense | "will return" instead of "returns" |
| Active voice | "is returned by the API" instead of "The API returns" |
| Tone | Arrogant ("Obviously...") or condescending |
---
## Structure Review
| Check | Flag If |
|-------|---------|
| Hierarchy | Deep nesting (H4+), unclear parent-child |
| Headings | Title Case instead of sentence case |
| Section dividers | Missing `---` between major topics |
| Navigation | Missing links to related content |
---
## Completeness Review
**Conceptual docs:** Definition, characteristics, how it works, related concepts, next steps
**How-to guides:** Prerequisites, all steps, verification, troubleshooting, next steps
**API docs:** HTTP method/path, all parameters, all fields, required vs optional, examples, error codes
---
## Clarity Review
| Check | Flag If |
|-------|---------|
| Sentence length | >25 words per sentence |
| Paragraph length | >3 sentences per paragraph |
| Jargon | Technical terms not explained on first use |
| Examples | Abstract data ("foo", "bar") instead of realistic |
---
## Technical Accuracy Review
**Conceptual:** Facts correct, behavior matches description, links work
**API docs:** Paths correct, methods correct, field names match API, types accurate, examples valid JSON
**Code examples:** Compiles/runs, output matches description, no syntax errors
---
## Common Issues to Flag
| Category | Issue | Fix |
|----------|-------|-----|
| Voice | Third person ("Users can...") | "You can..." |
| Voice | Passive ("...is returned") | "...returns" |
| Voice | Future tense ("will provide") | "provides" |
| Structure | Title case heading | Sentence case |
| Structure | Wall of text | Add `---` dividers |
| Completeness | Missing prereqs | Add prerequisites |
| Completeness | No examples | Add code examples |
| Clarity | Long sentences (40+ words) | Split into multiple |
| Clarity | Undefined jargon | Define on first use |
---
## Review Output Format
> **Note:** Documentation reviews use `PASS/NEEDS_REVISION/MAJOR_ISSUES` verdicts (graduated), which differ from code review verdicts (`PASS/FAIL/NEEDS_DISCUSSION`).
```markdown
## Review Summary
**Overall Assessment:** [PASS | NEEDS_REVISION | MAJOR_ISSUES]
### Issues Found
#### High Priority
1. **Line 45:** Passive voice "is created by" → "creates"
#### Medium Priority
1. **Line 23:** Title case in heading → sentence case
#### Low Priority
1. **Line 12:** Could add example for clarity
### Recommendations
1. Fix passive voice instances (3 found)
2. Add missing API field documentation
```
---
## Quick Review Checklist
**Voice (30s):** "You" not "users", present tense, active voice
**Structure (30s):** Sentence case headings, section dividers, scannable (bullets/tables)
**Completeness (1m):** Examples present, links work, next steps included
**Accuracy (varies):** Technical facts correct, code examples work
---
Related in Image & Video
watch
IncludedWatch a video (URL or local path). Downloads with yt-dlp, extracts auto-scaled frames with ffmpeg, pulls the transcript from captions (or Whisper API fallback), and hands the result to Claude so it can answer questions about what's in the video.
physical-ai-defect-image-generation
IncludedUse when the user wants to orchestrate defect image generation, run associated setup, or handle outputs on OSMO. The Day 0 path handles cold-start with USD-to-ROI, image-edit augmentation, and AnomalyGen to create initial PCBA datasets. The Day 1 path performs inference and labeling on real images. This skill helps with first-time asset setup, creation of finetuning checkpoints, and configuring deployment. Trigger keywords: defect image generation, dig workflow, dig pipeline, defect image detection workflow, aoi pipeline, aoi anomalygen, usd2roi anomalygen, day 0 pcba, day 1 pcba, day 1 real-photo alignment, day 1 manual roi, metal surface anomaly, glass defect, anomalygen finetune, setup_pcb, setup_metal, setup_glass, setup_pretrained, dig setup, dig datasets, dig pretrained checkpoint, dig image-edit endpoint.
accelint-react-best-practices
IncludedReact performance optimization and best practices. ALWAYS use this skill when working with any React code - writing components, hooks, JSX; refactoring; optimizing re-renders, memoization, state management; reviewing for performance; fixing hydration mismatches; debugging infinite re-renders, stale closures, input focus loss, animations restarting; preventing remounting; implementing transitions, lazy initialization, effect dependencies. Even simple React tasks benefit from these patterns. Covers React 19+ (useEffectEvent, Activity, ref props). Triggers - useEffect, useState, useMemo, useCallback, memo, inline components, nested components, components inside components, re-render, performance, hydration, SSR, Next.js, useDeferredValue, combined hooks.
elevenlabs-agents
IncludedBuild conversational AI voice agents with ElevenLabs Platform using React, JavaScript, React Native, or Swift SDKs. Configure agents, tools (client/server/MCP), RAG knowledge bases, multi-voice, and Scribe real-time STT. Use when: building voice chat interfaces, implementing AI phone agents with Twilio, configuring agent workflows or tools, adding RAG knowledge bases, testing with CLI "agents as code", or troubleshooting deprecated @11labs packages, Android audio cutoff, CSP violations, dynamic variables, or WebRTC config. Keywords: ElevenLabs Agents, ElevenLabs voice agents, AI voice agents, conversational AI, @elevenlabs/react, @elevenlabs/client, @elevenlabs/react-native, @elevenlabs/elevenlabs-js, @elevenlabs/agents-cli, elevenlabs SDK, voice AI, TTS, text-to-speech, ASR, speech recognition, turn-taking model, WebRTC voice, WebSocket voice, ElevenLabs conversation, agent system prompt, agent tools, agent knowledge base, RAG voice agents, multi-voice agents, pronunciation dictionary, voice speed control, elevenlabs scribe, @11labs deprecated, Android audio cutoff, CSP violation elevenlabs, dynamic variables elevenlabs, case-sensitive tool names, webhook authentication
humanizer
IncludedHumanize AI-generated text by detecting and removing patterns typical of LLM output. Rewrites text to sound natural, specific, and human. Uses 28 pattern detectors, 560+ AI vocabulary terms across 3 tiers, and statistical analysis (burstiness, type-token ratio, readability) for comprehensive detection. Use when asked to humanize text, de-AI writing, make content sound more natural/human, review writing for AI patterns, score text for AI detection, or improve AI-generated drafts. Covers content, language, style, communication, and filler categories.
generating-mermaid-diagrams
IncludedSalesforce architecture diagrams using Mermaid with ASCII fallback. Use this skill when generating text-based diagrams for Salesforce architecture, OAuth flows, ERDs, integration sequences, or Agentforce structure. TRIGGER when: user says "diagram", "visualize", "ERD", or asks for sequence diagrams, flowcharts, class diagrams, or architecture visualizations in Mermaid. DO NOT TRIGGER when: user wants PNG/SVG image output (use generating-visual-diagrams), or asks about non-Salesforce systems.