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/architecture-doc.md

View on GitHub
# Architecture document

**System:** Northstar Commerce  
**Version:** 1.2.0  
**Status:** Accepted  
**Audience:** Engineers joining the platform  
**Voice:** Google developer documentation style

This is the short C4-first cousin of `DESIGN_DOC.md`. Use it when the user wants system context, containers, and key sequences without the full arc42 ceremony. For regulated reviews, write the SDD instead.

---

## Purpose

Northstar lets a retailer publish a catalog, take payment, and hand a parcel to a carrier. This note shows where those responsibilities live and how a checkout call travels.

---

## System context

Shoppers and merchandizers are people. The PSP, the carrier, and email are external systems. Northstar is the single system of record for orders.

```mermaid
flowchart TB
  shopper([Shopper])
  merch([Merchandizer])
  ns[Northstar Commerce]
  psp[PSP]
  carrier[Carrier]
  email[Email]
  shopper -->|HTTPS| ns
  merch -->|HTTPS| ns
  ns -->|capture and refund| psp
  ns -->|label and track| carrier
  ns -->|receipt| email
```

---

## Containers

| Container | Tech | Role |
|-----------|------|------|
| Storefront | SSR web app | Shopper UI |
| Admin console | SPA | Merchandizing |
| API | Java 21 | Catalog, checkout, fulfillment |
| Postgres | Cloud SQL | Orders and catalog |
| Redis | Memorystore | Carts |
| Worker | Java 21 | Outbox drain |

```mermaid
flowchart LR
  shopper([Shopper]) --> web[Storefront]
  merch([Merchandizer]) --> admin[Admin]
  web --> api[API]
  admin --> api
  api --> pg[(Postgres)]
  api --> redis[(Redis)]
  api --> worker[Worker]
  worker --> pg
  worker --> psp[PSP]
  worker --> carrier[Carrier]
```

---

## Components inside the API

```mermaid
flowchart TB
  subgraph api [API]
    cat[Catalog]
    chk[Checkout]
    pay[Payments adapter]
    ful[Fulfillment]
  end
  cat --> chk
  chk --> pay
  chk --> ful
```

Catalog owns products and prices. Checkout owns orders. Payments never stores PAN. Fulfillment drains the outbox.

---

## Key sequence: checkout

Keep this to five participants.

```mermaid
sequenceDiagram
  participant W as Storefront
  participant A as API
  participant P as Payments
  participant D as Postgres
  participant Q as Worker

  W->>A: POST /orders
  A->>D: pending order
  A->>P: capture
  P-->>A: capture id
  A->>D: captured plus outbox
  A-->>W: 201
  Q->>D: read outbox
  Q->>Q: notify carrier
```

---

## Deployment

```mermaid
flowchart LR
  dns[HTTPS LB] --> web[Storefront pods]
  dns --> api[API pods]
  api --> pg[(Cloud SQL)]
  api --> redis[(Redis)]
  worker[Worker pods] --> pg
```

Staging mirrors production with a smaller replica. Promotes with a tagged image.

---

## Decisions to read next

- ADR-001 Modular monolith
- ADR-002 Transactional outbox

When a change crosses two containers or a quality goal, update this file and `DESIGN_DOC.md` in the same PR.

---

## UI wireframes

PlantUML Salt for the shopper checkout. Full catalog and admin screens are in the UI wireframes example.

```puml
@startuml
salt
{
  {+
    Northstar / Checkout
    {/ Cart | <b>Shipping | Payment | Review }
    Ship to
    { Address | "1200 Congress Ave" }
    { City    | "Austin" } | { ZIP | "78701" }
    Payment | PSP host field "•••• 4242"
    { [ Back ] | [ Place order ] }
  }
}
@enduml
```

---

## Use cases (PlantUML leftover)

GitHub wiki does not render the following source. Render PNG or SVG, commit it under `docs/diagrams/`, and upload the image with the wiki page.

```puml
@startuml
left to right direction
actor Shopper
actor Merchandizer
rectangle Northstar {
  usecase "Browse catalog" as UC1
  usecase "Place order" as UC2
  usecase "Refund order" as UC3
  usecase "Publish price" as UC4
}
Shopper --> UC1
Shopper --> UC2
Merchandizer --> UC3
Merchandizer --> UC4
@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: 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