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/ecommerce-sdd.md

View on GitHub
# DESIGN_DOC.md

**System:** Northstar Commerce  
**Version:** 1.2.0  
**Status:** Accepted  
**Audience:** Platform architects and service owners  
**Voice:** Google developer documentation style  
**Related requirements:** `docs/srs/billing-srs.md`

Northstar is a checkout and catalog platform for mid-market retailers. Shoppers browse a catalog, pay, and track fulfillment. Operators price, merchandize, and refund. This SDD records the architecture that satisfies those flows.

Use this file as the greenfield few-shot example when a user asks for a new software design document.

---

## 1. Introduction and goals

Northstar splits storefront, catalog, checkout, and fulfillment so pricing and payments can change without redeploying the storefront. The primary users are shoppers, merchandizers, and on-call operators.

### 1.1 Quality goals

| ID | Goal | Scenario |
|----|------|----------|
| QG-1 | Checkout availability | A region loss does not block capture for more than 60 seconds. |
| QG-2 | Price integrity | Two shoppers never pay different prices for the same SKU in the same second unless a promotion applies. |
| QG-3 | Auditability | Every capture, refund, and catalog publish has a trace id an auditor can pull. |

### 1.2 Stakeholders

| Stakeholder | Expectation |
|-------------|-------------|
| Shopper | Fast browse and a single-page checkout. |
| Merchandizer | Publish a price without an engineering ticket. |
| Payments lead | PCI scope stays inside the payments adapter. |
| On-call | One dashboard for order state. |

```mermaid
flowchart TD
  shopper([Shopper]) --> web[Storefront]
  merch([Merchandizer]) --> admin[Admin console]
  web --> api[Northstar API]
  admin --> api
  api --> pay[Payments provider]
  api --> ship[Fulfillment partner]
```

---

## 2. Constraints

- PCI-DSS SAQ A-EP. Card data never touches Northstar databases.
- Primary region `us-central1` with a warm `us-east1` replica.
- Java 21 and PostgreSQL 16 are the default runtime.
- Team of four. No more than six deployable units.

---

## 3. Context and scope

**In scope:** catalog browse, cart, checkout, capture, refund, shipment events.  
**Out of scope:** warehouse robotics, store POS, loyalty points.

```mermaid
flowchart TB
  shopper([Shopper])
  merch([Merchandizer])
  ns[Northstar Commerce]
  psp[Payment service provider]
  parcel[Parcel carrier]
  mail[Email provider]
  shopper --> ns
  merch --> ns
  ns --> psp
  ns --> parcel
  ns --> mail
```

---

## 4. Solution strategy

- Modular monolith first. Extract payments only if PCI scope forces it.
- Postgres for orders and catalog. Redis for cart sessions.
- Outbox pattern for shipment events. No dual writes.
- Server-side rendered storefront with a JSON API for the admin console.

ADR-001 chooses the modular monolith. ADR-002 chooses the outbox.

---

## 5. Building block view

| Building block | Responsibility | Requirements |
|----------------|----------------|--------------|
| Storefront | Browse, cart, checkout UI | FR-CAT-001, FR-CHK-001 |
| Catalog module | SKU, price, publish | FR-CAT-002 |
| Checkout module | Order, tax, capture handoff | FR-CHK-001, FR-PAY-001 |
| Payments adapter | PSP tokens, refunds | FR-PAY-001 |
| Fulfillment module | Shipment events | FR-FUL-001 |
| Admin console | Merchandizing | FR-CAT-002 |

```mermaid
flowchart TB
  subgraph northstar [Northstar]
    web[Storefront]
    admin[Admin console]
    cat[Catalog module]
    chk[Checkout module]
    pay[Payments adapter]
    ful[Fulfillment module]
    db[(Postgres)]
    redis[(Redis carts)]
  end
  web --> chk
  web --> cat
  admin --> cat
  chk --> pay
  chk --> ful
  chk --> db
  cat --> db
  web --> redis
```

### 5.1 Directory tree

```text
northstar/
  apps/storefront/
  apps/admin/
  modules/catalog/
  modules/checkout/
  modules/payments/
  modules/fulfillment/
  infra/
  docs/DESIGN_DOC.md
```

---

## 6. Runtime view

### 6.1 Place order

```mermaid
sequenceDiagram
  participant S as Shopper
  participant W as Storefront
  participant C as Checkout
  participant P as Payments adapter
  participant D as Postgres

  S->>W: Submit checkout
  W->>C: CreateOrder
  C->>D: Insert order pending
  C->>P: Capture token
  P-->>C: Capture id
  C->>D: Mark captured plus outbox
  C-->>W: Order confirmed
  W-->>S: Receipt
```

### 6.2 Order lifecycle

```mermaid
stateDiagram-v2
  [*] --> Pending
  Pending --> Captured: PSP ok
  Pending --> Failed: PSP decline
  Captured --> Fulfilling: outbox drained
  Fulfilling --> Shipped: carrier scan
  Shipped --> [*]
  Failed --> [*]
```

### 6.3 Catalog data

```mermaid
erDiagram
  PRODUCT ||--o{ SKU : has
  SKU ||--o{ PRICE : priced
  PRODUCT {
    uuid id PK
    string name
    string status
  }
  SKU {
    uuid id PK
    uuid product_id FK
    string code
  }
  PRICE {
    uuid id PK
    uuid sku_id FK
    numeric amount
    string currency
  }
  ORDER ||--|{ ORDER_LINE : contains
  ORDER {
    uuid id PK
    string state
    string trace_id
  }
```

---

## 7. Deployment view

```mermaid
flowchart LR
  browser[Browser]
  gclb[HTTPS load balancer]
  ssr[Storefront pods]
  api[API pods]
  pg[(Cloud SQL)]
  redis[(Memorystore)]
  browser --> gclb --> ssr
  gclb --> api
  api --> pg
  api --> redis
```

Two GKE namespaces, `prod` and `staging`. Secrets in Secret Manager. Traces on every checkout span.

---

## 8. Crosscutting concepts

- Authn: OIDC for admin. Session cookie for shoppers.
- Idempotency keys on capture and refund.
- Structured logs with `trace_id` and `order_id`.
- Feature flags for payment PSPs.

### 8.1 UI wireframes

Salt sketches for the two shopper screens. Card PAN never appears on the checkout wireframe.

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

```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"
    .
    { [ Back to cart ] | [ Place order ] }
  }
}
@enduml
```

---

## 9. Architectural decisions

### ADR-001: Modular monolith

**Status:** Accepted  
**Context:** Four engineers. Payments must stay isolatable.  
**Decision:** One deployable API with Maven modules.  
**Consequences:** Simple ops today. A future extract of `modules/payments` is a package move, not a rewrite.  
**Alternatives:** Microservices rejected. Too many moving parts for the team size.

### ADR-002: Transactional outbox

**Status:** Accepted  
**Context:** Dual writes to Postgres and a queue drift.  
**Decision:** Outbox table in the same transaction as the order row.  
**Consequences:** At-least-once delivery. Consumers must be idempotent.

---

## 10. Quality requirements

| ID | Requirement | Risk | Verify |
|----|-------------|------|--------|
| NFR-AVL-001 | Checkout capture remains available through a single-zone loss | High | Game day |
| NFR-AUD-001 | Every capture stores PSP id, token last4, and trace id | High | Audit query |

---

## 11. Risks and technical debt

- Tax tables are still a CSV loaded at boot. Owner: catalog team. Mitigation: move to a versioned table in Q3.
- Admin console shares the shopper API. Split authz filters before adding more roles.

---

## 12. Glossary

| Term | Meaning |
|------|---------|
| Capture | Funds pulled from the PSP token. |
| Outbox | Table of pending domain events written with the business row. |
| SKU | Sellable unit under a product. |
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