Initial commit

commands/review-docs.md

@@ -0,0 +1,110 @@
+---
+name: review-docs
+description: Review existing documentation for quality, voice, tone, and completeness
+argument-hint: "[file]"
+arguments:
+  - name: file
+    description: Path to the documentation file to review
+    required: false
+---
+
+# Review Documentation Command
+
+You're reviewing documentation quality. This command dispatches the docs-reviewer agent.
+
+## Review Process
+
+The review covers five dimensions:
+
+### 1. Voice and Tone
+- Uses "you" not "users"
+- Present tense for current behavior
+- Active voice (subject does action)
+- Assertive but not arrogant
+- Sounds like helping a colleague
+
+### 2. Structure
+- Sentence case headings
+- Section dividers between major topics
+- Scannable (bullets, tables, headings)
+- Logical hierarchy
+
+### 3. Completeness
+- All sections present
+- Examples included
+- Links work
+- Next steps provided
+
+### 4. Clarity
+- Short sentences (one idea)
+- Short paragraphs (2-3 sentences)
+- Jargon explained
+- Realistic examples
+
+### 5. Technical Accuracy
+- Facts are correct
+- Code examples work
+- Links valid
+- Version info current
+
+## Dispatch Review Agent
+
+```
+Task tool:
+  subagent_type: "ring-tw-team:docs-reviewer"
+  model: "opus"
+  prompt: "Review this documentation for quality. Check:
+          1. Voice and tone (second person, active voice, present tense)
+          2. Structure (sentence case, dividers, scannable)
+          3. Completeness (examples, links, next steps)
+          4. Clarity (short sentences, no jargon)
+          5. Accuracy (facts, code, links)
+
+          Provide:
+          - VERDICT: PASS / NEEDS_REVISION / MAJOR_ISSUES
+          - Prioritized issues with locations and fixes
+          - What was done well
+
+          Documentation to review:
+          [paste or reference file content]"
+```
+
+## Quick Checklist
+
+### Voice (scan for these)
+- [ ] No "users" or "one" (should be "you")
+- [ ] No "will" for current behavior (should be present tense)
+- [ ] No "is created by" (should be active: "creates")
+
+### Structure (scan for these)
+- [ ] Headings are sentence case
+- [ ] `---` dividers present
+- [ ] Content is scannable
+
+### Completeness (check for)
+- [ ] Examples present
+- [ ] Links work
+- [ ] Next steps at end
+
+## Verdict Criteria
+
+**PASS:** No critical issues, ≤2 high-priority issues, consistent voice/tone
+
+**NEEDS_REVISION:** Has high-priority issues, some inconsistencies, minor gaps
+
+**MAJOR_ISSUES:** Critical issues, significant problems, poor structure
+
+## Common Issues Reference
+
+| Issue | Example | Fix |
+|-------|---------|-----|
+| Third person | "Users can..." | "You can..." |
+| Passive voice | "...is returned" | "...returns" |
+| Title case | "Getting Started" | "Getting started" |
+| Missing prereqs | Steps without context | Add prerequisites |
+| No examples | API without code | Add examples |
+| Long sentences | 40+ words | Split into multiple |
+
+Now proceed with reviewing documentation.
+
+$ARGUMENTS.file ? Read the file at: **$ARGUMENTS.file** : Paste or specify the documentation to review.