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/templates/markdown/DESIGN_DOC.md

View on GitHub
# DESIGN_DOC.md template

**System:** `[System name]`  
**Version:** `[0.1.0]`  
**Status:** `[Proposed | Accepted]`  
**Audience:** `[Architects, implementers, reviewers]`  
**Voice:** `[STE100 | google-docs-style]`  
**Related requirements:** `[SRS or PRD path]`

Replace every `[placeholder]`. Keep the twelve arc42 sections. Insert Mermaid where the slots say so. Use PlantUML only for leftover types, and always link a PNG or SVG beside the source.

Save this file as `DESIGN_DOC.md` at the project root or as `docs/DESIGN_DOC.md`.

---

## 1. Introduction and goals

`[One or two paragraphs. What the system does. Which problem it solves. Who uses it.]`

### 1.1 Quality goals

| ID | Goal | Scenario |
|----|------|----------|
| QG-1 | `[e.g. auditability]` | `[concrete scenario]` |
| QG-2 | `[e.g. recoverability]` | `[concrete scenario]` |
| QG-3 | `[e.g. latency]` | `[concrete scenario]` |

### 1.2 Stakeholders

| Stakeholder | Expectation |
|-------------|-------------|
| `[role]` | `[what they need from this document]` |

```mermaid
flowchart TD
  user([Primary user]) --> sys[System under design]
  sys --> dep[Key dependency]
```

---

## 2. Constraints

- Business: `[budget, timeline, team shape]`
- Technical: `[language, cloud, datastore]`
- Legal: `[PCI, HIPAA, SOC2, data residency]`

---

## 3. Context and scope

Describe the system boundary. Name every actor and every external system. Then draw context.

**In scope:** `[list]`  
**Out of scope:** `[list]`

```mermaid
flowchart TB
  actor[Actor]
  sys[System name]
  ext[External system]
  db[(Datastore)]
  actor --> sys
  sys --> ext
  sys --> db
```

---

## 4. Solution strategy

`[The few high-level choices that drive the rest of the design. Link ADRs.]`

- ADR-001: `[decision]`
- ADR-002: `[decision]`

---

## 5. Building block view

List modules, packages, or containers. One sentence each. Then draw the static decomposition.

| Building block | Responsibility | Requirements |
|----------------|----------------|--------------|
| `[name]` | `[does what]` | `[FR-ids]` |

```mermaid
flowchart TB
  subgraph system [System name]
    api[API container]
    worker[Worker]
    store[(Store)]
  end
  api --> worker
  worker --> store
```

### 5.1 Directory tree

```text
[paste a trimmed tree of the repo]
```

---

## 6. Runtime view

Pick two or three use cases. Keep each sequence at five participants or fewer. Prefer subsystems over classes.

### 6.1 `[Use case name]`

```mermaid
sequenceDiagram
  participant U as User
  participant A as API
  participant W as Worker
  participant D as Store
  U->>A: Request
  A->>W: Command
  W->>D: Persist
  D-->>W: Ack
  W-->>A: Result
  A-->>U: Response
```

### 6.2 Lifecycle

```mermaid
stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Succeeded: ok
  Running --> Failed: error
  Failed --> Running: retry
  Succeeded --> [*]
```

---

## 7. Deployment view

```mermaid
flowchart LR
  client[Client]
  edge[Load balancer]
  svc[Service]
  db[(Primary DB)]
  client --> edge --> svc --> db
```

Runtime: `[process model, regions, secrets, observability]`.

---

## 8. Crosscutting concepts

- Logging and tracing: `[...]`
- Authn and authz: `[...]`
- Error handling: `[...]`
- Configuration: `[...]`
- Extensibility: `[...]`

---

## 9. Architectural decisions

Copy the ADR mini-template for each significant choice.

### ADR-001: `[title]`

**Status:** `[Proposed | Accepted]`  
**Context:** `[forces]`  
**Decision:** `[what]`  
**Consequences:** `[positive and negative]`  
**Alternatives:** `[rejected options and why]`

---

## 10. Quality requirements

| ID | Requirement | Risk | Verify |
|----|-------------|------|--------|
| NFR-001 | `[The system shall ...]` | High | Test |

---

## 11. Risks and technical debt

- `[risk or debt item, owner, mitigation]`

---

## 12. Glossary

| Term | Meaning |
|------|---------|
| `[term]` | `[definition used in this document]` |

### Required figures

Every `DESIGN_DOC.md` includes at least:

1. Context flowchart (section 3)
2. Building-block flowchart (section 5)
3. One sequence diagram (section 6)
4. One state or ER diagram if the domain has a lifecycle or a schema
5. Deployment flowchart (section 7)
6. PlantUML Salt wireframe for every user-facing screen

PlantUML use-case, Salt wireframe, timing, ArchiMate, nwdiag, or WBS go in `docs/diagrams/` as `.puml` plus PNG or SVG. Keep the Salt fence in `DESIGN_DOC.md` so reviewers can edit the screen.

### UI wireframe slot

```puml
@startuml
salt
{
  {+
    [Screen title]
    { Field | "value" }
    { [ Cancel ] | [ Primary action ] }
  }
}
@enduml
```
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