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/brownfield/spring-boot-sdd.md

View on GitHub
# DESIGN_DOC.md

**System:** Pet Clinic API  
**Version:** reverse-engineered from `src/main/java`  
**Status:** Draft  
**Audience:** Maintainers of the brownfield service  
**Voice:** Google developer documentation style  
**Source tree:** `spring-petclinic` (Spring Boot 3)

This SDD is the brownfield few-shot example. Every type name and path below is the kind of fact an agent must extract from code. Do not invent controllers that grep did not find.

---

## 1. Introduction and goals

Pet Clinic is a Spring Boot service for veterinarians. Staff register owners, pets, and visits. The original sample is a monolith with Thymeleaf. This document describes the extracted API module an agent would recover from package scans.

### 1.1 Quality goals

| ID | Goal | Scenario |
|----|------|----------|
| QG-1 | Accurate extraction | Every `@RestController` appears in section 5. |
| QG-2 | Operability | A new on-call can find health, datasource, and deploy shape. |

```mermaid
flowchart TD
  staff([Clinic staff]) --> api[Pet Clinic API]
  api --> db[(H2 or Postgres)]
```

---

## 2. Constraints

- Spring Boot 3, Java 17.
- JPA entities in `org.springframework.samples.petclinic.model`.
- Default sample uses H2. Production overlay uses Postgres.

---

## 3. Context and scope

**In scope:** owners, pets, vets, visits, REST plus the original web UI if present.  
**Out of scope:** billing, insurance, imaging.

```mermaid
flowchart TB
  staff([Clinic staff])
  sys[Pet Clinic]
  db[(Database)]
  staff -->|HTTP| sys
  sys --> db
```

---

## 4. Solution strategy

Classic Spring layered monolith: controllers, services, repositories, JPA entities. No message bus in the sample. Persistence is transactional per request.

---

## 5. Building block view

Detected from mappings in `spring-boot-mapping.yaml` style scans.

| Building block | Evidence | Responsibility |
|----------------|----------|----------------|
| `OwnerController` | `@Controller` / `@RestController` | Owner CRUD |
| `PetController` | same | Pets under an owner |
| `VetController` | same | Veterinarian list |
| `VisitController` | same | Visit create |
| `ClinicService` | `@Service` | Use-case orchestration |
| `*Repository` | Spring Data | Persistence |

```mermaid
classDiagram
  class OwnerController {
    +showOwner()
    +processCreationForm()
  }
  class ClinicService {
    +findOwnerById()
    +saveVisit()
  }
  class Owner {
    +id
    +lastName
    +pets
  }
  class Pet {
    +id
    +name
    +visits
  }
  OwnerController --> ClinicService
  ClinicService --> Owner
  Owner "1" --> "*" Pet
```

### 5.1 Directory tree

```text
src/main/java/org/springframework/samples/petclinic/
  owner/
  pet/
  vet/
  visit/
  model/
  system/
src/main/resources/application.properties
```

---

## 6. Runtime view

### 6.1 Record a visit

```mermaid
sequenceDiagram
  participant C as Client
  participant V as VisitController
  participant S as ClinicService
  participant R as VisitRepository
  participant D as Database

  C->>V: POST /owners/{id}/pets/{pid}/visits
  V->>S: saveVisit
  S->>R: save
  R->>D: INSERT
  D-->>R: row
  R-->>S: Visit
  S-->>V: Visit
  V-->>C: 201 or redirect
```

### 6.2 Visit state

The sample visit is append-only. There is no explicit status field. If you add cancellations, extend this diagram.

```mermaid
stateDiagram-v2
  [*] --> Scheduled: saveVisit
  Scheduled --> [*]
```

### 6.3 Schema recovered from entities

```mermaid
erDiagram
  OWNER ||--o{ PET : owns
  PET ||--o{ VISIT : attends
  VET ||--o{ VET_SPECIALTY : has
  SPECIALTY ||--o{ VET_SPECIALTY : listed
  OWNER {
    int id PK
    string lastName
    string telephone
  }
  PET {
    int id PK
    int owner_id FK
    string name
  }
  VISIT {
    int id PK
    int pet_id FK
    date visitDate
    string description
  }
```

---

## 7. Deployment view

```mermaid
flowchart LR
  client[Browser or API client]
  app[Spring Boot jar]
  db[(H2 or Postgres)]
  client --> app --> db
```

Local: `mvn spring-boot:run`. Production overlay: container, Postgres URL, Actuator `/health`.

---

## 8. Crosscutting concepts

- Validation on form objects.
- Actuator for health.
- Thymeleaf error pages in the web module.
- Transactions on `ClinicService`.

### 8.1 UI wireframes

Recovered from Thymeleaf templates. Owners search and new visit.

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

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

---

## 9. Architectural decisions

### ADR-B-001: Layered Spring monolith

**Status:** Observed, not chosen in this pass  
**Context:** The sample predates this SDD.  
**Decision:** Keep the layered package layout until a module boundary is proven.  
**Consequences:** Fast onboarding. Harder independent scaling.

---

## 10. Quality requirements

| ID | Requirement | Verify |
|----|-------------|--------|
| NFR-EXT-001 | Newly added controllers appear in section 5 after the next brownfield run | Diff the SDD |

---

## 11. Risks and technical debt

- H2 default hides production lock and migration issues.
- Web and API share entities. JSON views are incomplete.

---

## 12. Glossary

| Term | Meaning |
|------|---------|
| Owner | Pet owner on file. |
| Visit | Appointment row, not a streaming event. |
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