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/reference/04-diagrams-selection.md

View on GitHub
# Diagram playbook

Use this with `references/workflows/diagram-workflow.md`. Default tool is Mermaid. PlantUML is leftover types and images.

Cap a figure at about 16 nodes. Prefer several small diagrams over one dense one.

---

## Chooser

| You need to show | Diagram | Tool |
|------------------|---------|------|
| Who talks to the system | Context flowchart | Mermaid |
| Deployable pieces | Container flowchart | Mermaid |
| Modules inside a container | Component flowchart or class | Mermaid |
| Time-ordered calls | Sequence | Mermaid |
| Branching process | Flowchart | Mermaid |
| Lifecycle | State | Mermaid |
| Tables and keys | ER | Mermaid |
| Types and inheritance | Class | Mermaid |
| Nested ideas | Mind map | Mermaid |
| Schedule | Gantt | Mermaid |
| Shall-statements | Requirement | Mermaid |
| User feeling over time | Journey | Mermaid |
| Wire format | Packet | Mermaid |
| Actors and goals | Use case | PlantUML |
| UI sketch | Salt wireframe | PlantUML |
| Clock / waveform | Timing | PlantUML |
| Enterprise layers | ArchiMate | PlantUML |
| Rack / network | nwdiag | PlantUML |
| Breakdown structure | WBS | PlantUML |

If GitHub fails to render C4, `architecture-beta`, or `block-beta`, rewrite as `flowchart TD`. Do not switch to PlantUML for that reason on wiki.

---

## Flowchart

Process, decisions, or C4-style boxes.

```mermaid
flowchart TD
  start([Start]) --> ingest[Read request]
  ingest --> ok{Valid?}
  ok -->|yes| save[Write DESIGN_DOC.md]
  ok -->|no| ask[Ask one clarifying question]
  save --> done([Done])
  ask --> done
```

Direction: `TD` for documents, `LR` for deployment. Multi-line labels use `<br>`.

---

## Sequence

Keep five participants or fewer. Use subsystems, not every class.

```mermaid
sequenceDiagram
  participant A as Architect
  participant H as Host
  participant S as Skill
  A->>H: Write SDD
  H->>S: Load design-workflow
  S-->>H: DESIGN_DOC.md
  H-->>A: Path
```

---

## State

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> InReview: PR opened
  InReview --> Accepted: LGTM
  InReview --> Draft: changes requested
  Accepted --> [*]
```

---

## Class

```mermaid
classDiagram
  class DocumentSpecialist {
    +classifyIntent()
    +loadWorkflow()
    +writeDesignDoc()
  }
  class Workflow {
    +steps
  }
  class Template {
    +placeholders
  }
  DocumentSpecialist --> Workflow
  DocumentSpecialist --> Template
```

---

## ER

```mermaid
erDiagram
  PROJECT ||--o{ DOCUMENT : has
  DOCUMENT ||--o{ FIGURE : includes
  DOCUMENT {
    string path PK
    string kind
  }
  FIGURE {
    string id PK
    string tool
  }
```

---

## User journey

```mermaid
journey
  title Architect requests an SDD
  section Ask
    Name the system: 4: Architect
    Point at the repo: 5: Architect
  section Generate
    Classify intent: 4: Skill
    Draw figures: 3: Skill
  section Review
    Read DESIGN_DOC.md: 5: Architect
    Request edits: 3: Architect
```

---

## Mind map

```mermaid
mindmap
  root((Figures))
    Behavior
      Sequence
      State
      Flowchart
    Structure
      Class
      ER
      Context
    Leftover
      Use case
      Salt
      Timing
```

---

## Gantt

```mermaid
gantt
  title SDD first cut
  dateFormat YYYY-MM-DD
  section Draft
  Context and goals     :a1, 2026-09-01, 2d
  Building blocks       :a2, after a1, 2d
  section Figures
  Sequence and ER       :a3, after a2, 2d
  Review                :a4, after a3, 1d
```

---

## Requirement

```mermaid
requirementDiagram
  requirement design_doc {
    id: "FR-SDD-001"
    text: "The skill shall emit DESIGN_DOC.md"
    risk: High
    verifymethod: Inspection
  }
  element template {
    type: Document
  }
  template - satisfies -> design_doc
```

---

## Packet

```mermaid
packet-beta
0-15: "Skill id"
16-31: "Intent"
32-63: "Workflow"
64-95: "Template"
96-127: "Voice pack"
```

---

## Salt wireframe

Use PlantUML Salt for every UI, mock, or screen. Mermaid has no wireframe type. One screen per diagram.

```puml
@startuml
salt
{
  {* File | Edit | View }
  {+
    {/ <b>Library | DESIGN_DOC | Wireframes }
    .
    Find owner
    { Last name | "Davis" | [ Find Owner ] }
    [ Add Owner ]
    .
    {#
      Last name | First name | Pets
      Davis     | Betty      | Basil
      Davis     | Harold     | Iggy
    }
  }
}
@enduml
```

Copy labels from the real product. Full Folio, Northstar, and Pet Clinic screens are in the UI wireframes example.

---

## PlantUML leftover: use case

Render this to PNG or SVG. Do not leave it as the only view on GitHub wiki.

```puml
@startuml
left to right direction
actor Architect
rectangle "Document Specialist" {
  usecase "Write SDD" as UC1
  usecase "Write architecture" as UC2
  usecase "Extract from code" as UC3
}
Architect --> UC1
Architect --> UC2
Architect --> UC3
@enduml
```

---

## Formatting notes

- Set direction explicitly (`TD`, `LR`).
- Quote labels that contain punctuation.
- Style with `classDef` when you need contrast. Prefer theme variables over one-off hex in every node.
- Break a crowded figure into two linked diagrams rather than shrinking fonts.
- For wiki: keep the `mermaid` fence. For Confluence, Notion, Word, or PDF: render PNG or SVG and upload the image.
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