skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/solution-architect/skills/api-contract-draft/templates/openapi-skeleton.yaml

@@ -0,0 +1,148 @@
+# OpenAPI 3.1 skeleton — one fully-worked resource (refunds) showing every convention.
+# Replace the resource; keep the structure, the Problem schema, and the security wiring.
+openapi: 3.1.0
+info:
+  title: "{Service} API"
+  version: "1.0.0"
+  license: { name: "{license, e.g. Proprietary}" }
+  description: |
+    Versioning policy: additive changes (new optional fields, new endpoints, new enum
+    values on open enums) do not bump the major version; removals, renames, type
+    changes, and semantic changes do. Deprecated operations carry `deprecated: true`,
+    a Sunset header, and a named replacement.
+servers:
+  - url: https://api.example.com/v1
+security:
+  - bearerAuth: []
+paths:
+  /refunds:
+    post:
+      operationId: createRefund
+      summary: Request a refund for a captured payment
+      description: |
+        Retry guidance: retryable on 429 (honor Retry-After) and 503; never retryable
+        on other 4xx. Replays with the same Idempotency-Key return the original response.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string, format: uuid }
+          description: Retained 24h. Same key + different body returns 409.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RefundCreateRequest" }
+            example:
+              payment_id: "pay_8f4k2mq7"
+              amount: 2500
+              currency: "EUR"
+              reason: "customer_request"
+      responses:
+        "201":
+          description: Refund created and queued for processing.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Refund" }
+              example:
+                id: "ref_3j9x1pd4"
+                payment_id: "pay_8f4k2mq7"
+                amount: 2500
+                currency: "EUR"
+                reason: "customer_request"
+                status: "pending"
+                created_at: "2026-06-10T14:02:11Z"
+        "400":
+          description: "Validation failed. codes: validation_failed"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+        "402":
+          description: "Refund exceeds refundable balance. codes: insufficient_refundable_amount"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+        "404":
+          description: "Payment not found. codes: payment_not_found"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+        "409":
+          description: "Idempotency conflict. codes: idempotency_key_reused"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+    get:
+      operationId: listRefunds
+      summary: List refunds
+      parameters:
+        - { name: cursor, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 } }
+        - { name: payment_id, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { $ref: "#/components/schemas/RefundStatus" } }
+        - { name: sort, in: query, schema: { type: string, enum: ["created_at", "-created_at"], default: "-created_at" } }
+      responses:
+        "200":
+          description: Paginated refunds, newest first by default.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, next_cursor]
+                properties:
+                  data: { type: array, items: { $ref: "#/components/schemas/Refund" } }
+                  next_cursor: { type: [string, "null"] }
+  /refunds/{refund_id}:
+    get:
+      operationId: getRefund
+      summary: Fetch one refund
+      parameters:
+        - { name: refund_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: The refund.
+          content: { application/json: { schema: { $ref: "#/components/schemas/Refund" } } }
+        "404":
+          description: "codes: refund_not_found"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+components:
+  securitySchemes:
+    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
+  schemas:
+    RefundStatus:
+      type: string
+      description: "Closed enum — clients may exhaustively switch."
+      enum: [pending, processing, succeeded, failed]
+    RefundCreateRequest:
+      type: object
+      required: [payment_id, amount, currency]
+      properties:
+        payment_id: { type: string, maxLength: 64 }
+        amount: { type: integer, minimum: 1, description: "Minor units (cents)." }
+        currency: { type: string, pattern: "^[A-Z]{3}$", description: "ISO 4217." }
+        reason:
+          type: string
+          description: "Open enum — clients must tolerate unknown values."
+          enum: [customer_request, duplicate, fraud, other]
+    Refund:
+      type: object
+      required: [id, payment_id, amount, currency, status, created_at]
+      properties:
+        id: { type: string }
+        payment_id: { type: string }
+        amount: { type: integer, minimum: 1 }
+        currency: { type: string, pattern: "^[A-Z]{3}$" }
+        reason: { type: string, enum: [customer_request, duplicate, fraud, other] }
+        status: { $ref: "#/components/schemas/RefundStatus" }
+        failure_code: { type: [string, "null"], description: "Set only when status=failed." }
+        created_at: { type: string, format: date-time }
+    Problem:
+      type: object
+      required: [type, title, status, code]
+      properties:
+        type: { type: string, format: uri }
+        title: { type: string }
+        status: { type: integer }
+        code: { type: string, pattern: "^[a-z0-9_]+$" }
+        detail: { type: string }
+        errors:
+          type: array
+          items:
+            type: object
+            required: [field, code]
+            properties:
+              field: { type: string }
+              code: { type: string }
+              message: { type: string }

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: architecture-diagrams
+description: Generate architecture diagrams (Mermaid, PlantUML, C4) from a written description of a system. Supports AWS/Azure/GCP cloud topologies, microservice landscapes, sequence flows, container diagrams, and ER models. Use whenever the user asks for an architecture diagram, system sketch, flow diagram, or visualization of a design.
+---
+
+# architecture-diagrams
+
+You help the user turn a written system description into a clean, renderable architecture diagram.
+
+## How to respond
+
+1. **Clarify only what blocks correctness.** Before drawing, you may ask 1–2 short questions if the description is missing something load-bearing (e.g., "Is auth synchronous or via a sidecar?"). Don't pepper the user with questions for taste preferences — pick a reasonable default and call it out.
+
+2. **Pick the right notation.** Use this rough mapping unless the user requests otherwise:
+
+   | User's intent | Use |
+   |---|---|
+   | Cloud architecture (AWS/Azure/GCP) — boxes, arrows, services | **Mermaid** `flowchart` or `graph` |
+   | Request flow across services / call order matters | **Mermaid** `sequenceDiagram` |
+   | Strategic / multi-level view (context → container → component) | **C4 (PlantUML !include c4)** |
+   | Data model, tables, relationships | **Mermaid** `erDiagram` |
+   | State machine / workflow | **Mermaid** `stateDiagram-v2` |
+   | Class / type hierarchy | **Mermaid** `classDiagram` |
+   | Looks-pretty UML-style for slides | **PlantUML** |
+
+3. **Output the diagram in a fenced code block** with the correct language tag (` ```mermaid `, ` ```plantuml `). Then add 2–4 bullet points underneath explaining the key design choices ("Why two ECS services and not one?") so the diagram is reviewable, not just renderable.
+
+4. **Offer next steps**, e.g., "Want me to export this as SVG via the Mermaid CLI?" or "Want me to push this into a Figma file? (use the `figma-diagrams` skill)".
+
+## Useful references in this skill
+
+When you need a starting shape, copy from one of the templates rather than inventing notation from scratch — it cuts down on syntax errors and keeps style consistent across diagrams.
+
+- [`templates/mermaid-flowchart.md`](templates/mermaid-flowchart.md) — basic boxes-and-arrows starter
+- [`templates/mermaid-sequence.md`](templates/mermaid-sequence.md) — sequenceDiagram with actors and async messages
+- [`templates/mermaid-aws.md`](templates/mermaid-aws.md) — AWS-flavoured flowchart using emojis as service icons
+- [`templates/c4-container.puml`](templates/c4-container.puml) — C4 container diagram skeleton (PlantUML)
+
+Worked examples to learn from:
+
+- [`examples/aws-three-tier.md`](examples/aws-three-tier.md) — three-tier web app on AWS, Mermaid flowchart
+- [`examples/microservices-sequence.md`](examples/microservices-sequence.md) — order-placement flow across 4 services
+- [`examples/c4-container-saas.md`](examples/c4-container-saas.md) — SaaS app, C4 container level
+
+## Quality bar
+
+A good diagram from this skill should:
+
+- **Fit on one screen.** If you have more than ~15 nodes, split into two diagrams (e.g., "Context" and "Container") rather than cramming everything in.
+- **Show direction of data flow,** not just connections. Arrows should mean something.
+- **Label every arrow** that crosses a trust boundary or a network hop.
+- **Use subgraphs / groups** to make zones explicit (VPC, public/private subnets, account boundaries, on-prem vs cloud).
+- **Be valid syntax.** Mentally trace through the Mermaid/PlantUML once before responding. Common breakers: unescaped `(` `)` `<` `>` inside labels, missing `end` for subgraphs, mixing graph types.
+
+## What this skill does NOT do
+
+- It doesn't render to PNG/SVG itself. To render, suggest the user use the Mermaid Live Editor (https://mermaid.live), the Mermaid CLI (`mmdc`), or the VS Code Mermaid preview.
+- It doesn't push to Figma directly. For that, hand off to the [`figma-diagrams`](../figma-diagrams/SKILL.md) skill.
+- It doesn't generate Visio/Lucid native files.
+
+## Anti-patterns to avoid
+
+- ❌ Inventing service names ("ServiceA", "ServiceB"). Use the user's vocabulary or ask.
+- ❌ Putting every box at the top level. Group by concern.
+- ❌ Mermaid flowchart with 30+ nodes — split it.
+- ❌ Using a sequence diagram when the user asked "what does the system look like" — that's a structural question, use a flowchart or C4.

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Draw an architecture diagram for this system",
+    "should_trigger": true
+  },
+  {
+    "query": "Generate a Mermaid diagram of these services",
+    "should_trigger": true
+  },
+  {
+    "query": "Create a C4 container diagram from this description",
+    "should_trigger": true
+  },
+  {
+    "query": "Diagram the sequence flow I just described",
+    "should_trigger": true
+  },
+  {
+    "query": "Reverse-engineer the architecture from our Terraform and repo",
+    "should_trigger": false
+  },
+  {
+    "query": "Read the frames in our Figma file",
+    "should_trigger": false
+  },
+  {
+    "query": "Threat model this design",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the design doc for this system",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill_name": "architecture-diagrams",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Draw the architecture for a checkout service: an API gateway, an orders service, a payments service calling Stripe, and a Postgres primary with a read replica.",
+      "assertions": [
+        "The diagram fits on one screen; beyond roughly 15 nodes it is split into separate Context and Container diagrams rather than crammed",
+        "Arrows show direction of data flow, not undirected connections",
+        "Every arrow crossing a trust boundary is labelled",
+        "The diagram is generated from the written description provided — no components are invented beyond it",
+        "A named format is produced (Mermaid, PlantUML, or C4) and renders as valid syntax"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/examples/aws-three-tier.md

@@ -0,0 +1,44 @@
+# Example: Three-tier web app on AWS
+
+**Prompt the user gave:** *"Draw me a three-tier web app on AWS with an ALB, two ECS services (web + worker), and an RDS Postgres backend."*
+
+**Response:**
+
+```mermaid
+flowchart TB
+    Internet([🌐 Internet])
+
+    subgraph AWS["☁️ AWS us-east-1"]
+        subgraph VPC["🛡️ VPC 10.0.0.0/16"]
+            subgraph PubSub["Public subnet"]
+                ALB[🔀 Application Load Balancer]
+            end
+            subgraph PrivSub["Private subnet"]
+                Web[📦 ECS web service]
+                Worker[📦 ECS worker service]
+            end
+            subgraph DataSub["Data subnet"]
+                RDS[(🐘 RDS Postgres Multi-AZ)]
+            end
+        end
+        SQS{{📨 SQS jobs}}
+        S3[(🪣 S3 user uploads)]
+    end
+
+    Internet -->|HTTPS 443| ALB
+    ALB -->|HTTP 8080| Web
+    Web -->|SQL| RDS
+    Web -->|enqueue| SQS
+    Worker -->|dequeue| SQS
+    Worker -->|SQL| RDS
+    Web -.signed URLs.-> S3
+```
+
+**Design notes:**
+
+- **Why two ECS services and not one?** Long-running background work (image resize, email, exports) needs its own scaling profile and shouldn't share CPU with request-serving containers.
+- **RDS Multi-AZ** for automatic failover — single-AZ is fine for dev/test but rarely acceptable in production for a three-tier app.
+- **Uploads bypass the API** via S3 pre-signed URLs to avoid a 100 MB file streaming through ECS containers.
+- **No NAT gateway shown** — add one (or VPC endpoints) if the private subnet containers need to reach S3/SQS over the AWS network without a public IP.
+
+**Want to extend?** Common follow-ups: add CloudFront in front of ALB, add ElastiCache Redis for sessions, add WAF rules, split into multi-region active/passive.

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/examples/c4-container-saas.md

@@ -0,0 +1,51 @@
+# Example: C4 container diagram for a SaaS app
+
+**Prompt the user gave:** *"Give me a C4 container view of a B2B SaaS app — single tenant per database schema, with Stripe for billing."*
+
+**Response:**
+
+```plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_WITH_LEGEND()
+
+title Container diagram — Acme SaaS
+
+Person(admin, "Tenant admin", "Configures workspace, invites users")
+Person(user, "End user", "Day-to-day usage")
+
+System_Boundary(saas, "Acme SaaS") {
+    Container(web, "Web app", "Next.js", "Tenant-aware UI")
+    Container(api, "API", "Node, Fastify", "REST/JSON, business logic")
+    Container(worker, "Worker", "Python, Celery", "Async jobs, billing sync")
+    ContainerDb(db, "Tenant DB", "Postgres", "One schema per tenant")
+    ContainerDb(cache, "Cache", "Redis", "Session + rate-limit")
+    ContainerQueue(queue, "Job queue", "SQS", "Async work")
+}
+
+System_Ext(stripe, "Stripe", "Subscriptions + invoicing")
+System_Ext(idp, "Auth0", "OIDC identity provider")
+System_Ext(post, "Postmark", "Transactional email")
+
+Rel(admin, web, "Uses", "HTTPS")
+Rel(user, web, "Uses", "HTTPS")
+Rel(web, idp, "Auth (OIDC)", "HTTPS")
+Rel(web, api, "Calls", "HTTPS / JSON")
+Rel(api, db, "Reads/writes (per-tenant schema)", "SQL")
+Rel(api, cache, "Reads/writes", "RESP")
+Rel(api, queue, "Publishes", "HTTPS")
+Rel(worker, queue, "Consumes", "HTTPS")
+Rel(worker, db, "Reads/writes", "SQL")
+Rel(worker, stripe, "Syncs subscriptions", "HTTPS")
+Rel(worker, post, "Sends mail", "HTTPS")
+Rel(stripe, api, "Webhooks (invoice.*)", "HTTPS")
+@enduml
+```
+
+**Design notes:**
+
+- **One schema per tenant** is shown via the relationship label on `api -> db` — keeps the diagram clean while making the isolation strategy reviewable.
+- **Webhooks back from Stripe** (note arrow reversal) — a common trip-up; if it's missing, billing state drift is hard to debug.
+- **Worker hits external services**, not the API — avoids the API being a chokepoint for outbound integrations and keeps retries close to the queue.
+- For **context-level** (one box per system, no internals), drop everything inside `System_Boundary` and replace with one `System(saas, ...)`. For **component-level** (one container's internals), drill into `api` with `C4_Component.puml`.

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/examples/microservices-sequence.md

@@ -0,0 +1,49 @@
+# Example: Order placement across microservices
+
+**Prompt the user gave:** *"Show me the sequence of calls when a customer places an order — we have an Order service, an Inventory service, a Payment service, and a Notification service."*
+
+**Response:**
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor C as Customer
+    participant W as Web frontend
+    participant O as Order service
+    participant I as Inventory service
+    participant P as Payment service
+    participant N as Notification service
+    participant Q as Event bus
+
+    C->>W: Click "Place order"
+    W->>O: POST /orders
+    O->>I: Reserve(items)
+    alt items in stock
+        I-->>O: ReservationId
+        O->>P: Charge(amount, cardToken)
+        alt payment OK
+            P-->>O: PaymentId
+            O->>Q: Publish OrderPlaced
+            O-->>W: 201 Created
+            W-->>C: "Order confirmed"
+            Q-->>N: OrderPlaced
+            N->>C: Email + push notification
+        else payment declined
+            P-->>O: 402 Declined
+            O->>I: Release(reservationId)
+            O-->>W: 402 Payment failed
+            W-->>C: "Card declined"
+        end
+    else out of stock
+        I-->>O: 409 OutOfStock
+        O-->>W: 409 Unavailable
+        W-->>C: "Sold out"
+    end
+```
+
+**Design notes:**
+
+- **Two-step inventory** (reserve → confirm) avoids the classic race where two customers buy the last unit between stock-check and charge.
+- **Compensating action** (`Release`) on payment failure — explicit in the diagram so reviewers can spot the rollback gap if it's missing.
+- **Notification is async** (event bus, dashed line) — slow email shouldn't block the customer's response.
+- **`autonumber`** makes every step referenceable in design-review comments ("what happens at step 8?").

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/manifest.json

@@ -0,0 +1,31 @@
+{
+  "name": "architecture-diagrams",
+  "version": "0.1.0",
+  "description": "Generate architecture diagrams (Mermaid, PlantUML, C4) from a written description of a system. Supports AWS/Azure/GCP cloud topologies, microservice landscapes, sequence flows, container diagrams, and ER models. Use whenever the user asks for an architecture diagram, system sketch, flow diagram, or visualization of a design.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "figma-diagrams"
+  ],
+  "handoff": [
+    { "to": "figma-diagrams", "when": "the diagram needs to live where designers work", "purpose": "Push the rendered diagram into Figma.", "fallback": "If figma-diagrams is absent, leave the Mermaid source and say it needs manual import; never fabricate a Figma URL." }
+  ],
+  "tags": [
+    "diagrams",
+    "mermaid",
+    "plantuml",
+    "c4",
+    "architecture"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Prose to diagram syntax. Correctness matters; reasoning is bounded."
+  }
+}

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/templates/c4-container.puml

@@ -0,0 +1,31 @@
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_WITH_LEGEND()
+
+title Container diagram for <System name>
+
+Person(user, "End user", "Description of who this is")
+
+System_Boundary(sys, "<System name>") {
+    Container(web, "Web application", "React, TypeScript", "Customer-facing UI")
+    Container(api, "API", "Node, Express", "REST API, business logic")
+    Container(worker, "Background worker", "Python, Celery", "Async jobs, retries")
+    ContainerDb(db, "Primary DB", "PostgreSQL 16", "Customer + transactional data")
+    ContainerDb(cache, "Cache", "Redis 7", "Session + hot lookups")
+    ContainerQueue(queue, "Job queue", "RabbitMQ", "Async work coordination")
+}
+
+System_Ext(stripe, "Stripe", "Payment provider")
+System_Ext(ses, "AWS SES", "Transactional email")
+
+Rel(user, web, "Uses", "HTTPS")
+Rel(web, api, "Calls", "HTTPS / JSON")
+Rel(api, db, "Reads/writes", "SQL/TCP")
+Rel(api, cache, "Reads/writes", "RESP")
+Rel(api, queue, "Publishes jobs", "AMQP")
+Rel(worker, queue, "Consumes jobs", "AMQP")
+Rel(worker, db, "Reads/writes", "SQL/TCP")
+Rel(api, stripe, "Charges", "HTTPS / JSON")
+Rel(worker, ses, "Sends email", "HTTPS / JSON")
+@enduml

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/templates/mermaid-aws.md

@@ -0,0 +1,52 @@
+# AWS-flavoured Mermaid starter
+
+Mermaid doesn't ship native AWS icons, but emojis + clear naming get you 80% of the visual clarity for free, and the diagram still renders anywhere Markdown does.
+
+```mermaid
+flowchart TB
+    Internet([🌐 Internet])
+
+    subgraph AWS["☁️ AWS — us-east-1"]
+        subgraph VPC["🛡️ VPC 10.0.0.0/16"]
+            subgraph Public["Public subnet"]
+                ALB[🔀 ALB]
+            end
+            subgraph Private["Private subnet"]
+                ECS1[📦 ECS web]
+                ECS2[📦 ECS worker]
+            end
+            subgraph DataZone["Data"]
+                RDS[(🐘 RDS Postgres)]
+                Redis[(⚡ ElastiCache)]
+            end
+        end
+        S3[(🪣 S3 assets)]
+        SQS{{📨 SQS queue}}
+    end
+
+    Internet --> ALB --> ECS1
+    ECS1 --> Redis
+    ECS1 --> RDS
+    ECS1 --> SQS --> ECS2
+    ECS2 --> RDS
+    ECS1 -.reads.-> S3
+```
+
+## Service → emoji cheat sheet
+
+| Service | Emoji | Service | Emoji |
+|---|---|---|---|
+| EC2 / ECS / Fargate | 📦 | RDS / Aurora | 🐘 |
+| Lambda | λ or ⚡ | DynamoDB | 🗄️ |
+| S3 | 🪣 | ElastiCache | ⚡ |
+| ALB / NLB / API GW | 🔀 | CloudFront | 🌍 |
+| SQS / SNS | 📨 | EventBridge | 🚌 |
+| Cognito / IAM | 🔐 | KMS | 🔑 |
+| Route 53 | 🧭 | CloudWatch | 📊 |
+
+## Tips
+
+- Use `subgraph` to make VPC → subnet → service nesting visible — it's the single biggest readability win.
+- Mark public vs private subnets explicitly.
+- Dotted arrows (`-.label.->`) for async / read-only / observability paths so the primary request path stays prominent.
+- For multi-region, draw one region in detail and a thin "replica" box for the others, with a labeled arrow between them.

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/templates/mermaid-flowchart.md

@@ -0,0 +1,37 @@
+# Mermaid flowchart starter
+
+Use for: boxes-and-arrows structural diagrams. Top-down (`TD`) reads like a deployment stack; left-right (`LR`) reads like a request flow.
+
+```mermaid
+flowchart LR
+    User([User])
+
+    subgraph Edge["Edge"]
+        CDN[CDN]
+        WAF[WAF]
+    end
+
+    subgraph App["App tier"]
+        LB[Load balancer]
+        Web1[Web server 1]
+        Web2[Web server 2]
+    end
+
+    subgraph Data["Data tier"]
+        DB[(Primary DB)]
+        Cache[(Cache)]
+    end
+
+    User --> CDN --> WAF --> LB
+    LB --> Web1 & Web2
+    Web1 & Web2 --> Cache
+    Web1 & Web2 --> DB
+```
+
+## Tips
+
+- `[Box]` rectangle · `([Stadium])` user/external · `[(Cylinder)]` database · `{Diamond}` decision · `>Flag]` event
+- Use `&` to fan-out from one source to many destinations: `LB --> Web1 & Web2 & Web3`
+- Use `subgraph Name["Display label"]` to draw zones (VPC, account, region)
+- Annotate links with `--label-->` to name the arrow
+- Pick *one* direction (`TD`, `LR`) per diagram; mixing kills readability

skilldrop_cli/data/packs/solution-architect/skills/architecture-diagrams/templates/mermaid-sequence.md

@@ -0,0 +1,39 @@
+# Mermaid sequence diagram starter
+
+Use for: showing the **order** of messages between participants. Best when "who calls whom in what order" is the question.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Web as Web app
+    participant API as API gateway
+    participant Auth as Auth service
+    participant DB as Database
+
+    User->>Web: Click "sign in"
+    Web->>API: POST /login {email, pwd}
+    API->>Auth: Validate credentials
+    Auth->>DB: SELECT user WHERE email=?
+    DB-->>Auth: User row
+    Auth-->>API: JWT (15 min) + refresh
+    API-->>Web: Set-Cookie, 200 OK
+    Web-->>User: Dashboard
+
+    Note over API,Auth: All hops over mTLS
+```
+
+## Tips
+
+- `->>` solid arrow (call) · `-->>` dashed arrow (return/async) · `-x` lost message
+- `autonumber` adds 1, 2, 3 to each step — great for design reviews
+- `Note over A,B: text` annotates a span; `Note left of A: text` annotates one side
+- `loop`, `alt`/`else`, `par` for control flow:
+  ```
+  alt token valid
+      API-->>Web: 200
+  else token expired
+      API-->>Web: 401
+  end
+  ```
+- Don't overuse — past ~12 messages it becomes a wall. Split into "happy path" and "error path" diagrams.