Skip to content

SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist

documentation-specialist

Verified

This 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".

FileKindSize
SKILL.mdskill md10.0 KB
references/examples/TOC.mdmarkdown6.5 KB
references/examples/brownfield/database-failover-runbook.mdmarkdown8.1 KB
references/examples/brownfield/spring-boot-sdd.mdmarkdown5.6 KB
references/examples/greenfield/adr-microservices.mdmarkdown6.3 KB
references/examples/greenfield/architecture-doc.mdmarkdown3.7 KB
references/examples/greenfield/billing-srs.mdmarkdown12.4 KB
references/examples/greenfield/cli-getting-started.mdmarkdown9.3 KB
references/examples/greenfield/collaboration-prd.mdmarkdown13.8 KB
references/examples/greenfield/document-specialist-sdd.mdmarkdown15.4 KB
references/examples/greenfield/ecommerce-sdd.mdmarkdown7.8 KB
references/examples/greenfield/rest-api-tutorial.mdmarkdown13.8 KB
references/examples/greenfield/task-api-openapi.yamlconfig19.0 KB
references/examples/greenfield/taskmanager-user-manual.mdmarkdown8.7 KB
references/examples/greenfield/ui-wireframes.mdmarkdown5.8 KB
references/guides/requirements/README.mdmarkdown3.7 KB
references/mappings/backend/fastapi-mapping.yamlconfig9.7 KB
references/mappings/backend/spring-boot-mapping.yamlconfig24.1 KB
references/reference/01-philosophy.mdmarkdown2.0 KB
references/reference/02-requirements-srs-vs-prd.mdmarkdown1.2 KB
references/reference/02-requirements-traceability.mdmarkdown1.7 KB
references/reference/02-requirements-writing.mdmarkdown1.4 KB
references/reference/03-design-adrs.mdmarkdown2.2 KB
references/reference/03-design-arc42.mdmarkdown2.6 KB
references/reference/03-design-requirements-matrix.mdmarkdown1.3 KB
references/reference/04-diagrams-c4-hierarchy.mdmarkdown2.0 KB
references/reference/04-diagrams-selection.mdmarkdown5.1 KB
references/reference/04-diagrams-state-vs-activity.mdmarkdown2.3 KB
references/reference/05-api-checklist.mdmarkdown2.0 KB
references/reference/05-api-openapi.mdmarkdown3.4 KB
references/reference/05-api-stripe-gold-standard.mdmarkdown1.8 KB
references/reference/06-deployment-diagrams.mdmarkdown1.8 KB
references/reference/06-deployment-documentation.mdmarkdown2.9 KB
references/reference/06-deployment-runbooks.mdmarkdown2.5 KB
references/reference/06-operational-docs.mdmarkdown2.7 KB
references/reference/07-user-kb-approach.mdmarkdown1.8 KB
references/reference/07-user-kb-template.mdmarkdown3.1 KB
references/reference/07-user-writing-style.mdmarkdown2.0 KB
references/reference/08-agile-process.mdmarkdown3.2 KB
references/reference/08-tutorial-writing.mdmarkdown7.4 KB
references/reference/09-code-to-docs-detection.mdmarkdown2.5 KB
references/reference/09-code-to-docs-example.mdmarkdown3.2 KB
references/reference/09-code-to-docs-when.mdmarkdown1.7 KB
references/reference/09-code-to-docs-workflow.mdmarkdown2.0 KB
references/reference/10-quality-bonsai-pruning.mdmarkdown2.4 KB
references/reference/10-quality-checklist.mdmarkdown2.6 KB
references/reference/10-quality-metrics.mdmarkdown3.1 KB
references/reference/11-voice-and-style.mdmarkdown1.5 KB
references/reference/comprehensive-guide.mdmarkdown7.3 KB
references/templates/markdown/DESIGN_DOC.mdmarkdown4.5 KB
references/templates/markdown/api-openapi.yamlconfig17.7 KB
references/templates/markdown/architecture.mdmarkdown1.6 KB
references/templates/markdown/design-sdd.mdmarkdown143 B
references/templates/markdown/developer-tutorial.mdmarkdown7.1 KB
references/templates/markdown/getting-started.mdmarkdown6.5 KB
references/templates/markdown/howto-guide.mdmarkdown4.1 KB
references/templates/markdown/requirements-prd.mdmarkdown10.2 KB
references/templates/markdown/requirements-srs.mdmarkdown17.0 KB
references/templates/markdown/runbook.mdmarkdown8.8 KB
references/templates/markdown/user-manual.mdmarkdown4.8 KB
references/workflows/TOC.mdmarkdown1.9 KB
references/workflows/audit-workflow.mdmarkdown2.5 KB
references/workflows/brownfield-workflow.mdmarkdown3.6 KB
references/workflows/brownfield/fastapi-guide.mdmarkdown1.8 KB
references/workflows/brownfield/pulumi-guide.mdmarkdown1.9 KB
references/workflows/brownfield/springboot-guide.mdmarkdown2.2 KB
references/workflows/convert-workflow.mdmarkdown1.4 KB
references/workflows/design-workflow.mdmarkdown3.0 KB
references/workflows/diagram-workflow.mdmarkdown3.7 KB
references/workflows/greenfield-workflow.mdmarkdown3.4 KB
references/workflows/greenfield/advanced.mdmarkdown1.9 KB
references/workflows/greenfield/openapi-guide.mdmarkdown2.5 KB
references/workflows/greenfield/prd-guide.mdmarkdown2.0 KB
references/workflows/greenfield/srs-guide.mdmarkdown2.0 KB
references/workflows/runbook-workflow.mdmarkdown2.4 KB
references/workflows/tutorial-workflow.mdmarkdown2.3 KB
references/workflows/user-docs-workflow.mdmarkdown2.3 KB

references/guides/requirements/README.md

View on GitHub
# Requirements Documentation Guides

This directory contains specialized guides for creating requirements documentation.

## Available Guides

### 1. srs-guide.md
**Software Requirements Specification (SRS)**
- Formal, comprehensive requirements documentation
- IEEE-standard compliant structure
- Best for: High-assurance, regulated, or enterprise projects
- Key sections: Introduction, Functional Requirements, Non-Functional Requirements, Use Cases

### 2. prd-guide.md
**Product Requirements Document (PRD)**
- Modern, agile requirements documentation
- Business-focused with clear success metrics
- Best for: Product development, startups, agile teams
- Key sections: Objective, Success Metrics, User Stories, Out of Scope

### 3. user-stories-guide.md
**User Stories**
- Atomic requirements from user perspective
- "As a [user], I want to [goal], so that [benefit]"
- Best for: Agile development, iterative projects
- Includes: Story format, acceptance criteria, story mapping

### 4. acceptance-criteria-guide.md
**Acceptance Criteria**
- Testable conditions for user story completion
- Given-When-Then (Gherkin) format
- BDD-style scenario writing
- Best for: Ensuring testability and clarity

### 5. requirements-best-practices.md
**General Best Practices**
- Clear, unambiguous language
- Testable requirements
- Requirements traceability
- MoSCoW prioritization
- Avoiding common pitfalls

### 6. context-diagrams-guide.md
**System Context Diagrams**
- C4 Level 1 context diagrams
- DFD Level 0 diagrams
- Defining system boundaries
- Identifying external actors and systems

## When to Use Which Guide

| Scenario | Recommended Guide |
|----------|-------------------|
| Enterprise system with formal approvals | srs-guide.md |
| Product feature for SaaS application | prd-guide.md |
| Agile sprint planning | user-stories-guide.md |
| Ensuring testability | acceptance-criteria-guide.md |
| System scoping | context-diagrams-guide.md |
| General requirements writing | requirements-best-practices.md |

## Common Patterns

### Pattern 1: Formal Project (Waterfall-ish)
1. Start with srs-guide.md
2. Add context-diagrams-guide.md for system boundary
3. Apply requirements-best-practices.md for quality

### Pattern 2: Agile Product Development
1. Start with prd-guide.md for product vision
2. Break down into user-stories-guide.md
3. Add acceptance-criteria-guide.md for testability

### Pattern 3: Hybrid (Risk-Based)
1. Use prd-guide.md for most features
2. Use srs-guide.md for high-risk modules (billing, security, compliance)
3. Always apply requirements-best-practices.md

## Integration with Other Documentation

Requirements documentation should link to:
- **Design Documentation**: Requirements Traceability Matrix maps requirements to design components
- **Test Documentation**: Each requirement should have associated test cases
- **User Documentation**: User-facing requirements inform user guide content

## Quality Checklist

Every requirements document should have:
- [ ] Unique identifiers for each requirement (FR-001, NFR-001)
- [ ] Clear, testable acceptance criteria
- [ ] Priority assigned (MoSCoW: Must/Should/Could/Won't)
- [ ] Traceability links (requirement → design → test)
- [ ] Stakeholder approval sign-off
- [ ] Version history

## Tools and Formats

- **Primary Format**: Markdown (for version control and docs-as-code)
- **Enterprise Format**: Word (DOCX) generated from markdown
- **Collaboration**: Confluence, Notion, or GitHub/GitLab wikis
- **Visual**: Mermaid or PlantUML for context diagrams

## Examples

See `examples/greenfield/` for complete requirements document examples:
- `project-atlas-prd.md` - Modern PRD example
- `project-atlas-srs.md` - Formal SRS example for billing module
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall