spillwavesolutions/document-specialist-skill/document-specialist-skill

Documentation Specialist Skill

Quick Start

Software documentation creation, extraction, conversion, and diagramming capabilities.

Capabilities:

1. Greenfield - Create documentation from templates (SRS, PRD, SDD/DESIGN_DOC.md, architecture, OpenAPI, User Manuals, Tutorials, Runbooks)
2. Brownfield - Reverse-engineer documentation from code (Spring Boot, FastAPI)
3. Audit - Review and improve existing documentation
4. Convert - Transform formats (MD to DOCX to PDF)
5. Diagram - Mermaid first (C4, sequence, class, ER, state, flowchart). PlantUML Salt for UI wireframes. PlantUML for leftover UML (use case, timing, ArchiMate, nwdiag, WBS).

Example Requests:

Create an SRS for a billing system with PCI-DSS compliance
Write DESIGN_DOC.md for this repository using arc42
Create an architecture document with C4-style Mermaid
Document my Spring Boot application at ~/projects/customer-api
Create a user manual for my SaaS product
Write a database failover runbook
Audit my API documentation at docs/api/openapi.yaml
Convert docs/srs.md to Word format
Create a C4 container diagram for my microservices
Draw a login wireframe

Execution Flow:

1. Classify intent to 2. Choose one voice pack to 3. Load workflow to 4. Execute steps to 5. Generate documentation to 6. Present post-processing options

Voice pack (required, pick one)

Every document this skill writes uses exactly one voice pack. Do not mix them.

Default is STE100. Switch only when the user names Google style. If both are named, ask which pack to use. Do not apply both.

Hard bans (both packs)

These apply even if a template or prior draft used them:

• Do not use an em dash (—) or a double hyphen standing in for one (-- as punctuation). Use a period or a comma.
• Do not start a sentence with So, That, Thus, or Hence.
• Do not start a sentence with a dangling demonstrative ("That is why..." as a lead).

STE100 also requires: short sentences, one instruction per step, active voice, no contractions, no e.g. / i.e. / etc., no weak modals in steps. Load 11-voice-and-style.md.

After the draft exists, run the chosen pack:

• STE100: follow the local orchestrator / editor / adversary loop in the ste100 skill. No network.
• Google style: run python3 scripts/google_docs_style.py --lint --check when that skill is installed.

Intent Classification

CRITICAL: Load only the workflow needed for the current intent. Avoid loading multiple workflows.

When intent is DESIGN, save the SDD as DESIGN_DOC.md (or docs/DESIGN_DOC.md). Save the short C4 form as docs/architecture.md.

Document Type to Template

Requirements and Design:

User Documentation:

Developer and Operations:

Framework Detection (Brownfield)

Process: Glob for detection files to Grep for patterns to Load mapping to Follow brownfield workflow

On-Demand Resources

Load only what is needed for the current task.

Workflows

• Workflow TOC - Navigation index
• design-workflow.md
• greenfield-workflow.md
• brownfield-workflow.md
• audit-workflow.md
• convert-workflow.md
• diagram-workflow.md
• user-docs-workflow.md
• tutorial-workflow.md
• runbook-workflow.md

Reference Guides

• comprehensive-guide.md - Navigation to all 27 reference guides
• 11-voice-and-style.md - STE100 vs Google style, hard bans
• 04-diagrams-selection.md - Mermaid first, PlantUML leftover types, Salt UI wireframes
• 03-design-arc42.md - The twelve arc42 sections

Examples

• Examples TOC - Navigation to all examples
• DESIGN: ecommerce-sdd.md, architecture-doc.md, ui-wireframes.md
• Brownfield SDD: spring-boot-sdd.md
• This skill's own SDD: DESIGN_DOC.md

Skill Integration

When WikiTicket SDD asks for an architecture doc, a code walkthrough, or a requirements doc, use this skill for prose and wireframes, design-doc-mermaid for every GitHub-safe diagram, and plantuml only for leftover types.

GitHub wiki: embed Mermaid. Upload PlantUML images with the page. Confluence: render Mermaid and PlantUML to PNG or SVG and upload both.

Error Handling

End of SKILL.md (v3.3.0)