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/examples/greenfield/ui-wireframes.md

View on GitHub
# UI wireframes (PlantUML Salt)

**System:** Document Specialist and example products  
**Tool:** PlantUML Salt  
**Voice:** Google developer documentation style

Mermaid cannot sketch screens. Use PlantUML Salt for every UI in an SDD or architecture document. Keep the `.puml` source, render PNG or SVG, and link the image. GitHub wiki does not render Salt fences.

This page is the few-shot set. Copy a wireframe, rename the window title, and swap labels for the product under design.

---

## Salt cheatsheet

| Mark | Control |
|------|---------|
| `"text"` | Text field |
| `[OK]` | Button |
| `[]` | Checkbox |
| `()` | Radio |
| `^` | Drop-down |
| `{* File \| Edit }` | Menu bar |
| `{/ Tab1 \| Tab2 }` | Tabs |
| `{+ ... }` | Window |
| `{T + item ++ child}` | Tree |
| `==` `--` `..` | Separators |
| `\|` | Table cell |

Prefix the diagram with `salt` inside `@startuml`. Do not use Mermaid `block-beta` for screens.

---

## Folio library

Landing view of the Document Specialist studio. Menu, tabs, and a two-up card grid.

```puml
@startuml
salt
{
  {* File | Edit | View | Plugins }
  {+
    {/ <b>Library | DESIGN_DOC | Diagrams | Plugins }
    .
    { Folio  |  Document Specialist  |  [ Download plugin ] }
    .
    SpillwaveSolutions / document-specialist-skill
    <b>Design documents the skill was missing
    .
    {^
      {
        <b>DESIGN_DOC.md
        Architects and skill authors
        arc42 SDD of Document Specialist
        [ Open ]
      } |
      {
        <b>Northstar commerce SDD
        Greenfield few-shot
        Checkout, catalog, payments
        [ Open ]
      }
    }
    {
      {
        <b>Architecture document
        C4-first short form
        [ Open ]
      } |
      {
        <b>UI wireframes
        PlantUML Salt
        [ Open ]
      }
    }
  }
}
@enduml
```

---

## Folio document paper

Reading an SDD. Outline on the left, paper in the center, copy and plugin actions on the toolbar.

```puml
@startuml
salt
{
  {* File | Edit | View }
  {+
    {/ Library | <b>DESIGN_DOC | Diagrams | Plugins }
    .
    {
      {
        Outline
        {T
         + DESIGN_DOC.md
         ++ 1. Introduction and goals
         ++ 3. Context and scope
         ++ 5. Building block view
         ++ 6. Runtime view
         ++ 8. UI wireframes
        }
      } |
      {
        DESIGN_DOC.md
        Architects and skill authors
        { [ Copy Markdown ] | [ Plugin ] }
        ..
        <b>Document Specialist design document
        .
        System  | Document Specialist skill
        Status  | Accepted
        Voice   | Google developer documentation style
        .
        == 1. Introduction and goals
        Document Specialist turns an agent
        into a documentation specialist.
        .
        [ Context diagram rendered here ]
      }
    }
  }
}
@enduml
```

---

## Northstar catalog

Shopper browse. Filters, product grid, cart count.

```puml
@startuml
salt
{
  {* Northstar | Catalog | Account | Help }
  {+
    {/ <b>Shop | Cart (2) | Orders }
    .
    { Search  | "linen shirt"  | [ Search ] }
    .
    {
      {
        Filters
        [] In stock
        [] On sale
        Size
        () XS
        () S
        () M
        () L
        Color  | ^White^
      } |
      {^
        {
          SKU-104
          <b>Oxford shirt
          $64
          [ Add to cart ]
        } |
        {
          SKU-221
          <b>Linen shirt
          $72
          [ Add to cart ]
        }
      }
    }
  }
}
@enduml
```

---

## Northstar checkout

Single-page checkout. Shipping, payment token, place order. Card number never appears. That is a PCI constraint.

```puml
@startuml
salt
{
  {+
    Northstar / Checkout
    {/ Cart | <b>Shipping | Payment | Review }
    .
    Ship to
    { Name     | "Alex Rivera" }
    { Address  | "1200 Congress Ave" }
    { City     | "Austin" } | { ZIP | "78701" }
    [] Billing address is the same
    .
    Payment
    PSP host field  | "•••• 4242"
    Expiry          | "09 / 28"
    .
    { [ Back to cart ] | [ Place order ] }
  }
}
@enduml
```

---

## Pet Clinic: owners

Brownfield staff UI recovered from Spring MVC templates. Search by last name, then open an owner.

```puml
@startuml
salt
{
  {* Pet Clinic | Owners | Vets | Help }
  {+
    {/ <b>Find owners | Veterinarians | Error }
    .
    Find owner
    { Last name | "Davis" | [ Find Owner ] }
    [ Add Owner ]
    .
    {#
      Last name | First name | City | Pets
      Davis     | Betty      | Madison | Basil
      Davis     | Harold     | McFarland | Iggy, Lucky
    }
  }
}
@enduml
```

---

## Pet Clinic: record a visit

```puml
@startuml
salt
{
  {+
    New visit for Iggy
    .
    { Owner | Harold Davis }
    { Pet   | Iggy  (dog) }
    { Date  | "2026-09-04" }
    { Description | "Annual vaccines" }
    .
    { [ Cancel ] | [ Add Visit ] }
  }
}
@enduml
```

---

## Document Specialist plugin hosts

Settings-style screen for the four manifests.

```puml
@startuml
salt
{
  {+
    Install Document Specialist
    {/ <b>Universal | Claude Code | Grok | Codex }
    .
    Agent Plugins 1.0
    plugin.json at the repo root
    skills/documentation-specialist/SKILL.md
    .
    [] Also pin .claude-plugin
    [] Also pin .grok-plugin
    [] Also pin .codex-plugin
    .
    Default prompt
    "Write DESIGN_DOC.md using arc42.
     Include Salt wireframes for every UI."
    .
    [ Copy install command ] | [ Download zip ]
  }
}
@enduml
```

---

## How agents should file these

1. Write Salt source under `docs/diagrams/[screen].puml`.
2. Render PNG or SVG. PlantUML server, `plantuml` CLI, or this studio.
3. Link the image from `DESIGN_DOC.md`. Keep the fence so reviewers can edit.
4. One screen per diagram. Do not nest an entire product in one Salt block.

When the user names a UI, a screen, a mock, or a wireframe, load this page and `design-workflow.md`, then emit Salt. Do not substitute a Mermaid flowchart for a screen.
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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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