SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist
documentation-specialist
VerifiedThis skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".
references/workflows/audit-workflow.md
View on GitHub# Documentation Audit Workflow
---
TOKEN_BUDGET: 350
TIER: 2
LOAD_TRIGGER: Intent = AUDIT
DEPENDENCIES: SKILL.md
---
## Overview
Review existing documentation for quality, completeness, and best practices.
**Audit Types**: SRS, PRD, SDD, OpenAPI, User Documentation
## Workflow Steps
### Step 1: Identify Document Type
| Indicators | Type | Focus |
|------------|------|-------|
| "FR-", "NFR-", "Requirements Specification" | SRS | Formal requirements |
| "User Stories", "Success Metrics" | PRD | Agile requirements |
| "arc42", "Architecture" | SDD | Design documentation |
| "openapi:", "paths:" | OpenAPI | API specification |
| "How to", "Step-by-step" | User Docs | End-user guides |
### Step 2: Run Quality Checklist
**All Documents**:
- [ ] Clear title, version, date
- [ ] Author/owner identified
- [ ] Table of contents (if > 3 pages)
- [ ] Introduction with purpose/scope
- [ ] Glossary of terms
- [ ] Consistent formatting
**Requirements (SRS/PRD)**:
- [ ] Unique IDs (FR-XXX-001)
- [ ] Testable criteria (Given-When-Then)
- [ ] NFRs included (performance, security)
- [ ] Priorities assigned
**API (OpenAPI)**:
- [ ] Base URL defined
- [ ] Authentication documented
- [ ] All endpoints described
- [ ] Error responses (4xx, 5xx)
- [ ] Request/response examples
### Step 3: Classify Issues
| Severity | Description |
|----------|-------------|
| **Critical** | Missing mandatory section, incorrect information |
| **High** | Incomplete coverage of important topic |
| **Medium** | Formatting, consistency issues |
| **Low** | Minor improvements, recommendations |
### Step 4: Generate Audit Report
```markdown
# Documentation Audit Report
**Document**: [name and path]
**Type**: [SRS|PRD|SDD|OpenAPI]
**Audit Date**: [date]
## Executive Summary
- **Quality**: [Excellent|Good|Fair|Poor]
- **Completeness**: [percentage]
- **Recommendation**: [Approve|Minor Revisions|Major Revisions]
## Critical Issues
[List with location, issue, impact, recommendation]
## High Priority Issues
[List with details]
## Quick Wins (< 1 hour)
[List of easy fixes]
## Next Steps
1. Fix critical issues
2. Address high priority items
3. Implement improvements
```
### Step 5: Present Fix Options
Present summary and options to user:
```
Found [X] critical, [Y] high priority, [Z] medium priority issues.
Options:
1. Automatically fix critical and high priority issues
2. Generate missing diagrams
3. Complete the glossary
4. Standardize formatting
```
## Quality Standards
For detailed criteria: [10-quality-checklist.md](../reference/10-quality-checklist.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |