skilldrop-cli 0.16.35 → 0.16.36

package/packs/solution-architect/skills/event-contract-draft/evals/evals.json

@@ -0,0 +1,76 @@
+{
+  "skill_name": "event-contract-draft",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We're moving fulfilment, loyalty and analytics off polling our order API and onto Kafka events. Our brief is in order-events-brief.md. Can you draft the event contract so the three teams can start building?",
+      "assertions": [
+        "Does not publish an event named CreateShipment; renames it to a past-tense fact in the order domain such as OrderPaid, and explains that the warehouse decides to pick when it sees that fact",
+        "Declines the analytics request for one global order across all orders, keys the order events by order id, and says what ordering that gives (per order) and what it does not (across orders)",
+        "Puts the order events whose relative order matters (paid, cancelled) on the same channel with the same key",
+        "Drops customerEmail because no listed consumer needs it, and keeps the delivery address for fulfilment marked as personal data",
+        "Does not rename total to totalAmount in place on the live OrderPlaced event; ships the change as a new field beside the old one or a new version published alongside the old, with a deprecation date that is agreed with fulfilment rather than invented",
+        "Every message carries a required envelope: event id, event type, version, occurred-at in UTC RFC 3339, producer and correlation id; money is integer minor units, not 42.50",
+        "States at-least-once delivery and says how each consumer stays idempotent (for example dedupe on event id, or loyalty points keyed on order id)",
+        "States retention (7 days, from the brief), whether consumers can replay, and what goes to a dead-letter queue, and lists who watches it as open rather than inventing a team",
+        "Does not invent volumes, dates, team names or consumers not in the brief; anything assumed is marked as an assumption"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Quick one: we publish PaymentCaptured and PaymentRefunded to Kafka, keyed by paymentId. The ledger team says they need to see the refund after the capture for the same order, and an order can have several payments. Are we covered?",
+      "assertions": [
+        "Answers in the first lines: no, not for the order as a whole",
+        "Explains that Kafka orders only within a partition, so keying by paymentId orders one payment's events but gives no order across payments of the same order",
+        "Recommends keying by order id (or giving a per-order sequence the ledger can sort on) if the ledger needs order-level ordering, and notes that changing the key on a live topic is a breaking change",
+        "Says delivery is at-least-once and the ledger must deduplicate on an event id",
+        "Is a short answer, not a full AsyncAPI document",
+        "Does not invent partition counts, volumes or team details not in the question"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We're a small invoicing SaaS. Customers want a webhook when an invoice is paid so their accounting system can mark it settled. Product wants us to include the payer's full card number and email in the payload so they can reconcile. Draft the webhook contract.",
+      "assertions": [
+        "Refuses to put the card number on the webhook and says so in the first lines, offering a card reference or last four digits instead",
+        "Leaves out the payer's email or justifies it with a named consumer need and marks it as personal data",
+        "Names the event as a past-tense fact such as InvoicePaid, with an event id, type, version, occurred-at in UTC and producer in every delivery",
+        "States that delivery is at-least-once with retries and that receivers must deduplicate on the event id",
+        "States that webhooks have no ordering guarantee and gives receivers a way to handle out-of-order or stale deliveries",
+        "Specifies a signature over the payload with a timestamp so receivers can verify the sender and reject replays",
+        "States the retry schedule or its cap and what happens to deliveries that keep failing, without inventing a customer or vendor name",
+        "Additive-only versioning is stated, and receivers are told to ignore unknown fields"
+      ]
+    },
+    {
+      "id": 4,
+      "held_out": "2026-10-20",
+      "prompt": "We're the tracking-core team at Parcelway. Our draft message schema for the `shipments` Kafka topic is in schemas/shipment-update.json and our working notes (consumers, incidents, plans) are in NOTES.md. Three teams consume it: notify-svc, analytics and billing. Before we lock it down for peak season, can you turn this into a proper contract the consumers can sign off on — an AsyncAPI doc plus whatever short write-up of the decisions they'll need — and tell us what's wrong with the current draft?",
+      "assertions": [
+        "Produces an AsyncAPI 3.0 document (asyncapi: 3.0.0, with channels and operations for the `shipments` topic and message schemas) plus a short decisions page, and also lists what is wrong with the current draft as asked.",
+        "Replaces the single imperative `UpdateShipment` / `action` enum with separate past-tense facts about the shipment, and specifically flags SEND_DELIVERY_SMS as a command to notify-svc rather than something that happened, removing it from the producer's contract.",
+        "Adds a required envelope with a unique event id and an unambiguous UTC (ISO 8601) occurrence time replacing the depot-local `dd/MM/yyyy HH:mm` timestamp, and ties the ~3,000 duplicate 'out for delivery' SMS after the rebalance to at-least-once redelivery, telling notify-svc and billing to deduplicate on the event id (billing must not charge or remit codAmount twice).",
+        "Changes the partition key from `carrierId` to `shipmentId`, explains that this gives ordering per shipment only (none across shipments or carriers), connects it to 'delivered' arriving before 'out_for_delivery', and warns that the planned 12 -> 48 partition increase in November remaps keys to partitions so per-shipment ordering can break around the change.",
+        "Applies data minimisation: drops `recipient.dateOfBirth` (and questions sending phone/email/address to every consumer, including analytics which keeps data forever), and marks whatever recipient PII remains as PII in the schema.",
+        "Rejects the Q1 plan to rename `status` -> `state` and switch `weight` from kg to grams as a v2 on the same topic, because both are breaking; proposes additive-only changes (e.g. a new field with an explicit unit) or a new topic/major version run in parallel with a dated deprecation for the old one.",
+        "Addresses retention, replay and dead letters: points out the 7-day default retention cannot support analytics replaying events from last year (needs longer retention, compaction or replay from the lake), and replaces billing's crash-restart loop on unparseable messages with a dead-letter topic and a defined redrive process; also flags codAmount as a float without currency.",
+        "Invents nothing that isn't in the input (no extra consumers, partition counts, incidents, field values or tooling claimed to exist beyond the two files), and answers the actual request directly — a contract plus the list of draft problems — without padding."
+      ]
+    },
+    {
+      "id": 5,
+      "held_out": "2026-10-20",
+      "prompt": "hey, we're finally doing outgoing webhooks at Ledgerly (invoicing SaaS). customers want to hear when an invoice gets paid, goes overdue or gets voided. PM says it HAS to be exactly once and in order because customers reconcile their books against it. plan rn: POST the whole invoice object to the customer's URL (example in invoice.example.json), add a header X-Ledgerly-Version: 1 and change the payload when we need to, our http client times out at 10s, retry 3x then give up. a couple of customers already told us their endpoint does ERP sync work before it responds and takes ~40s. so: how should we version these and how do we actually guarantee delivery? write up the spec thing too i guess",
+      "assertions": [
+        "Answers the two questions (versioning, guaranteed delivery) directly and early, and tells the user plainly that exactly-once delivery over HTTP webhooks is not achievable: the honest guarantee is at-least-once, with a unique event id on every delivery that receivers store to deduplicate.",
+        "States that ordering cannot be guaranteed across retries and parallel deliveries, and gives receivers a way to cope (e.g. use `updated_at` or a per-invoice sequence number to discard stale events, or re-fetch the invoice from the API) rather than promising in-order delivery.",
+        "Spots that the ~40s ERP-sync endpoints will always exceed the 10s client timeout, so every delivery to them would be retried and duplicated; advises receivers to acknowledge with a 2xx quickly and process asynchronously.",
+        "Replaces 'retry 3x then give up' with retries on a backoff schedule over a longer window, and after retries are exhausted keeps the event (dead-letter / failed-delivery log) with a way for customers to see and replay or redeliver it, instead of silently dropping it.",
+        "On versioning, rejects 'change the payload when we need to' under an unchanging header: proposes a version pinned per endpoint/account, additive-only changes within a version, and breaking changes only in a new version with a dated deprecation window for the old one.",
+        "Applies data minimisation to the payload: does not send `internal_notes`, and drops or justifies `customer.tax_id`, `customer.billing_address`, `customer.contact_email` and `payment.card_last4` (e.g. send a thin event with the invoice id and key fields, and let the receiver fetch details), marking any PII kept; also flags `amount`/`unit_amount` 1299.9 as a float and recommends integer minor units with `currency`.",
+        "Provides a compact AsyncAPI 3.0 document describing the webhook messages (a common envelope with event id, type and occurrence time, and messages for the paid/overdue/voided cases with past-tense names) plus a short decisions summary, and recommends signing deliveries (e.g. an HMAC signature header with a timestamp) so receivers can verify the sender and reject replays.",
+        "Invents nothing not in the input (no made-up existing Ledgerly endpoints, customer names, SLAs or numbers beyond 10s, 3 retries, ~40s and the example invoice), and keeps the answer sized to a chatty question — direct answers first, then the spec — rather than a sprawling design document."
+      ]
+    }
+  ]
+}

package/packs/solution-architect/skills/event-contract-draft/evals/files/1/order-events-brief.md

@@ -0,0 +1,45 @@
+# Order service: events we need to publish
+
+From the order service team at Brightcart (fictional), for review with the platform team.
+
+We want fulfilment and loyalty to stop polling our REST API every minute and react to events
+instead. The platform team runs Kafka for us; topics default to 7 days' retention.
+
+## Events we think we need
+
+1. **CreateShipment** — we send this when an order has been paid, so the warehouse starts
+   picking.
+2. **OrderCancelled** — a customer or support agent cancels an order before it is dispatched.
+3. **OrderPlaced** — we already publish this today on the topic `orders` (payload below), and
+   fulfilment consumes it in production. In the next release we want to rename `total` to
+   `totalAmount` and make it an integer in pence, to match the payments team's naming. We'd
+   like to just change it in place so there's only one version to maintain.
+
+## Who consumes what
+
+- **Fulfilment** (warehouse system): needs the order id, the lines (SKU and quantity) and the
+  delivery address. Starts picking only once the order is paid. Stops picking if it is
+  cancelled.
+- **Loyalty**: needs the customer id and the order total to award points, and takes the points
+  back when an order is cancelled.
+- **Analytics**: wants every order event from every order in one single global order, so their
+  dashboards replay exactly as things happened across the whole business.
+
+We'll put `customerEmail` on every event as well, just in case someone needs it later.
+
+## What OrderPlaced looks like today
+
+```json
+{
+  "orderId": "ord_7Q2K9",
+  "customerId": "cus_31F8",
+  "customerEmail": "jo.example@example.com",
+  "total": 42.50,
+  "currency": "GBP",
+  "lines": [{ "sku": "TEA-EB-250", "quantity": 2 }],
+  "deliveryAddress": { "line1": "1 Example Street", "town": "Exampleton", "postcode": "EX1 1AA" },
+  "placedAt": "2026-10-19 14:03:11"
+}
+```
+
+Nobody has decided yet who looks after failed messages.

package/packs/solution-architect/skills/event-contract-draft/evals/files/4/NOTES.md

@@ -0,0 +1,23 @@
+# shipments topic - working notes (tracking-core team)
+
+Producer: tracking-core. Kafka topic `shipments`, 12 partitions, key = `carrierId`
+(so each carrier's events stay together). Retention: cluster default, 7 days.
+
+## Consumers
+
+- **notify-svc** - texts/emails the recipient on status changes. Last month a consumer
+  group rebalance made it re-read a batch and ~3,000 recipients got the
+  "out for delivery" SMS twice. Also: sometimes "delivered" arrives before
+  "out_for_delivery" for the same parcel and customers get confused.
+- **analytics** - copies everything into the data lake, keeps it forever.
+  They want to be able to replay events from last year after they fixed a bug
+  in their pipeline.
+- **billing** - charges the merchant per delivered parcel and remits `codAmount`.
+  When it hits a message it can't parse, it crashes, restarts, reads the same
+  message, crashes again. Happened twice in September.
+
+## Plans
+
+- Peak season: bump `shipments` from 12 to 48 partitions in November.
+- Q1: rename `status` -> `state` and send `weight` in grams instead of kg.
+  Plan is to just bump the version to v2 on the same topic and tell consumers.

package/packs/solution-architect/skills/event-contract-draft/evals/files/4/schemas/shipment-update.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "UpdateShipment",
+  "description": "Draft v0.3 - one message type for everything that happens to a shipment. Published by tracking-core to the 'shipments' topic.",
+  "type": "object",
+  "properties": {
+    "action": {
+      "type": "string",
+      "enum": ["CREATE_SHIPMENT", "UPDATE_STATUS", "SEND_DELIVERY_SMS", "CANCEL"],
+      "description": "What to do with this shipment."
+    },
+    "shipmentId": { "type": "string", "description": "e.g. PW-48213377" },
+    "carrierId": { "type": "string", "description": "e.g. CARR-017" },
+    "status": {
+      "type": "string",
+      "enum": ["booked", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed_attempt", "returned"]
+    },
+    "recipient": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "phone": { "type": "string" },
+        "email": { "type": "string" },
+        "dateOfBirth": { "type": "string", "description": "Only needed for age-restricted parcels, but we always send it." },
+        "address": {
+          "type": "object",
+          "properties": {
+            "line1": { "type": "string" },
+            "city": { "type": "string" },
+            "postcode": { "type": "string" }
+          }
+        }
+      }
+    },
+    "weight": { "type": "number", "description": "Parcel weight (kg)." },
+    "codAmount": { "type": "number", "description": "Cash-on-delivery amount collected, e.g. 24.99" },
+    "timestamp": { "type": "string", "description": "When it happened, depot local time, format dd/MM/yyyy HH:mm" }
+  },
+  "required": ["action", "shipmentId"]
+}

package/packs/solution-architect/skills/event-contract-draft/evals/files/5/invoice.example.json

@@ -0,0 +1,25 @@
+{
+  "id": "inv_7Qd2KxP9",
+  "number": "INV-2026-00418",
+  "account_id": "acct_3mZt81",
+  "status": "paid",
+  "amount": 1299.9,
+  "currency": "EUR",
+  "due_date": "2026-10-31",
+  "updated_at": "2026-10-20T09:14:52Z",
+  "customer": {
+    "name": "Hollis & Varga GmbH",
+    "contact_email": "ap@hollis-varga.example",
+    "tax_id": "DE000000000",
+    "billing_address": "Musterweg 12, 10115 Berlin"
+  },
+  "payment": {
+    "method": "card",
+    "card_last4": "4242",
+    "paid_at": "2026-10-20T09:14:50Z"
+  },
+  "line_items": [
+    { "description": "Pro plan, October", "quantity": 1, "unit_amount": 1299.9 }
+  ],
+  "internal_notes": "Customer asked for net-30, approved by finance"
+}

package/packs/solution-architect/skills/event-contract-draft/examples/order-service.asyncapi.json

@@ -0,0 +1,246 @@
+{
+  "asyncapi": "3.0.0",
+  "info": {
+    "title": "Order service events",
+    "version": "1.0.0",
+    "description": "Facts the order service publishes about orders. Consumers: fulfilment, loyalty, analytics.\n\nConsumers must: (1) deduplicate on eventId, because delivery is at-least-once; (2) apply an event only when its orderRevision is higher than the last one applied for that order, and drop it otherwise; (3) ignore fields and event types they do not recognise; (4) never rely on order across different orders; (5) own the dead-letter queue for their consumer group.\n\nVersioning: within a version only optional fields are added. A breaking change ships as a new event version, published alongside the old one until the old one's sunset date, agreed with its consumers."
+  },
+  "defaultContentType": "application/json",
+  "servers": {
+    "production": {
+      "host": "kafka.example.internal:9092",
+      "protocol": "kafka",
+      "description": "Placeholder; the platform team supplies the real bootstrap servers."
+    }
+  },
+  "channels": {
+    "orderLifecycle": {
+      "address": "orders.order-lifecycle.v1",
+      "description": "Every state change of an order, in the order it happened for that order.",
+      "x-partition-key": "orderId",
+      "x-ordering": "Ordered per orderId: OrderPlaced, OrderPaid and OrderCancelled for one order arrive in the order the order service committed them. No order across orders and no global order. A retry can redeliver an earlier event; consumers compare orderRevision.",
+      "x-delivery": "at-least-once; duplicates come from producer retries, consumer rebalances and replays",
+      "x-retention": "7 days (platform default)",
+      "x-replay": "A consumer group can reset its offset to any point in the last 7 days.",
+      "x-dead-letter": "After 5 failed attempts [assumption] a consumer parks the message on <consumer-group>.orders.order-lifecycle.v1.dlq. Owner per consumer group: to confirm.",
+      "messages": {
+        "OrderPlacedV2": { "$ref": "#/components/messages/OrderPlacedV2" },
+        "OrderPaid": { "$ref": "#/components/messages/OrderPaid" },
+        "OrderCancelled": { "$ref": "#/components/messages/OrderCancelled" }
+      }
+    },
+    "ordersLegacy": {
+      "address": "orders",
+      "description": "Today's topic, carrying OrderPlaced v1 unchanged until its sunset date. Nothing new is added here.",
+      "x-partition-key": "to confirm: the current key on this topic is not stated",
+      "x-ordering": "Unchanged from today; no ordering promise is added. No global order.",
+      "x-delivery": "at-least-once",
+      "x-retention": "7 days (platform default)",
+      "x-replay": "A consumer group can reset its offset to any point in the last 7 days.",
+      "x-dead-letter": "As today; owner to confirm.",
+      "messages": {
+        "OrderPlacedV1": { "$ref": "#/components/messages/OrderPlacedV1" }
+      }
+    }
+  },
+  "operations": {
+    "publishOrderLifecycle": {
+      "action": "send",
+      "channel": { "$ref": "#/channels/orderLifecycle" },
+      "messages": [
+        { "$ref": "#/channels/orderLifecycle/messages/OrderPlacedV2" },
+        { "$ref": "#/channels/orderLifecycle/messages/OrderPaid" },
+        { "$ref": "#/channels/orderLifecycle/messages/OrderCancelled" }
+      ]
+    },
+    "publishOrdersLegacy": {
+      "action": "send",
+      "channel": { "$ref": "#/channels/ordersLegacy" },
+      "messages": [ { "$ref": "#/channels/ordersLegacy/messages/OrderPlacedV1" } ]
+    }
+  },
+  "components": {
+    "messages": {
+      "OrderPlacedV2": {
+        "name": "OrderPlacedV2",
+        "title": "Order placed (v2)",
+        "summary": "A customer placed an order. Not yet paid.",
+        "description": "Event-carried state: what the order contains. No delivery address: nobody acts on an unpaid order's address.",
+        "x-event-style": "event-carried-state",
+        "bindings": { "kafka": { "key": { "type": "string", "description": "orderId" } } },
+        "payload": {
+          "allOf": [
+            { "$ref": "#/components/schemas/Envelope" },
+            {
+              "type": "object",
+              "required": ["data"],
+              "properties": {
+                "eventType": { "type": "string", "const": "OrderPlaced" },
+                "eventVersion": { "type": "integer", "const": 2 },
+                "data": {
+                  "type": "object",
+                  "required": ["orderId", "orderRevision", "customerId", "lines", "totalAmount", "currency"],
+                  "properties": {
+                    "orderId": { "$ref": "#/components/schemas/OrderId" },
+                    "orderRevision": { "$ref": "#/components/schemas/OrderRevision" },
+                    "customerId": { "type": "string", "description": "Opaque id. Loyalty." },
+                    "lines": { "$ref": "#/components/schemas/Lines" },
+                    "totalAmount": { "$ref": "#/components/schemas/TotalAmount" },
+                    "currency": { "$ref": "#/components/schemas/Currency" }
+                  }
+                }
+              }
+            }
+          ]
+        },
+        "examples": [
+          {
+            "name": "placed",
+            "payload": {
+              "eventId": "8a1f3c52-4d6e-4b7a-9c0d-2e3f4a5b6c7d",
+              "eventType": "OrderPlaced",
+              "eventVersion": 2,
+              "occurredAt": "2026-10-19T14:03:11Z",
+              "producer": "order-service",
+              "correlationId": "1c9e7a40-55b2-4f0e-8d31-6a7b8c9d0e1f",
+              "data": {
+                "orderId": "ord_7Q2K9",
+                "orderRevision": 1,
+                "customerId": "cus_31F8",
+                "lines": [ { "sku": "TEA-EB-250", "quantity": 2 } ],
+                "totalAmount": 4250,
+                "currency": "GBP"
+              }
+            }
+          }
+        ]
+      },
+      "OrderPaid": {
+        "name": "OrderPaid",
+        "title": "Order paid",
+        "summary": "Payment for an order succeeded. Replaces the requested CreateShipment.",
+        "description": "Event-carried state: everything fulfilment needs to start picking and loyalty needs to award points, so neither calls the order API.",
+        "x-event-style": "event-carried-state",
+        "bindings": { "kafka": { "key": { "type": "string", "description": "orderId" } } },
+        "payload": {
+          "allOf": [
+            { "$ref": "#/components/schemas/Envelope" },
+            {
+              "type": "object",
+              "required": ["data"],
+              "properties": {
+                "eventType": { "type": "string", "const": "OrderPaid" },
+                "eventVersion": { "type": "integer", "const": 1 },
+                "data": {
+                  "type": "object",
+                  "required": ["orderId", "orderRevision", "customerId", "lines", "totalAmount", "currency", "deliveryAddress"],
+                  "properties": {
+                    "orderId": { "$ref": "#/components/schemas/OrderId" },
+                    "orderRevision": { "$ref": "#/components/schemas/OrderRevision" },
+                    "customerId": { "type": "string", "description": "Opaque id. Loyalty." },
+                    "lines": { "$ref": "#/components/schemas/Lines" },
+                    "totalAmount": { "$ref": "#/components/schemas/TotalAmount" },
+                    "currency": { "$ref": "#/components/schemas/Currency" },
+                    "deliveryAddress": {
+                      "type": "object",
+                      "x-pii": "fulfilment: where to ship",
+                      "required": ["line1", "town", "postcode"],
+                      "properties": {
+                        "line1": { "type": "string", "maxLength": 200 },
+                        "town": { "type": "string", "maxLength": 100 },
+                        "postcode": { "type": "string", "maxLength": 16 }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        }
+      },
+      "OrderCancelled": {
+        "name": "OrderCancelled",
+        "title": "Order cancelled",
+        "summary": "A customer or support agent cancelled an order before dispatch.",
+        "description": "Notification: ids and who cancelled. Fulfilment stops picking; loyalty reverses the points it awarded for this orderId.",
+        "x-event-style": "notification",
+        "bindings": { "kafka": { "key": { "type": "string", "description": "orderId" } } },
+        "payload": {
+          "allOf": [
+            { "$ref": "#/components/schemas/Envelope" },
+            {
+              "type": "object",
+              "required": ["data"],
+              "properties": {
+                "eventType": { "type": "string", "const": "OrderCancelled" },
+                "eventVersion": { "type": "integer", "const": 1 },
+                "data": {
+                  "type": "object",
+                  "required": ["orderId", "orderRevision", "customerId", "cancelledBy"],
+                  "properties": {
+                    "orderId": { "$ref": "#/components/schemas/OrderId" },
+                    "orderRevision": { "$ref": "#/components/schemas/OrderRevision" },
+                    "customerId": { "type": "string", "description": "Opaque id. Loyalty." },
+                    "cancelledBy": { "type": "string", "enum": ["customer", "support"], "description": "Closed enum." }
+                  }
+                }
+              }
+            }
+          ]
+        }
+      },
+      "OrderPlacedV1": {
+        "name": "OrderPlacedV1",
+        "title": "Order placed (v1, deprecated)",
+        "summary": "Today's event, documented as-is. Unchanged until sunset.",
+        "x-deprecated": true,
+        "x-sunset": "to agree with fulfilment",
+        "x-replaced-by": "OrderPlacedV2",
+        "payload": {
+          "type": "object",
+          "properties": {
+            "orderId": { "type": "string" },
+            "customerId": { "type": "string" },
+            "customerEmail": { "type": "string", "x-pii": "no consumer named; not carried in v2" },
+            "total": { "type": "number", "description": "Major units as a decimal (42.50). Replaced by totalAmount in v2." },
+            "currency": { "type": "string" },
+            "lines": { "$ref": "#/components/schemas/Lines" },
+            "deliveryAddress": { "type": "object", "x-pii": "fulfilment" },
+            "placedAt": { "type": "string", "description": "Local time with no zone, as published today." }
+          }
+        }
+      }
+    },
+    "schemas": {
+      "Envelope": {
+        "type": "object",
+        "required": ["eventId", "eventType", "eventVersion", "occurredAt", "producer", "correlationId"],
+        "properties": {
+          "eventId": { "type": "string", "format": "uuid", "description": "Unique per event; identical on every redelivery and replay." },
+          "eventType": { "type": "string" },
+          "eventVersion": { "type": "integer", "minimum": 1 },
+          "occurredAt": { "type": "string", "format": "date-time", "description": "When it happened, UTC, RFC 3339 with Z." },
+          "producer": { "type": "string", "const": "order-service" },
+          "correlationId": { "type": "string" },
+          "causationId": { "type": "string", "description": "eventId or request id that caused this event." }
+        }
+      },
+      "OrderId": { "type": "string", "pattern": "^ord_[A-Za-z0-9]+$" },
+      "OrderRevision": { "type": "integer", "minimum": 1, "description": "Increases by 1 on every change to this order." },
+      "TotalAmount": { "type": "integer", "minimum": 0, "description": "Order total in minor units (pence): 42.50 GBP is 4250." },
+      "Currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+      "Lines": {
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "object",
+          "required": ["sku", "quantity"],
+          "properties": {
+            "sku": { "type": "string" },
+            "quantity": { "type": "integer", "minimum": 1 }
+          }
+        }
+      }
+    }
+  }
+}

package/packs/solution-architect/skills/event-contract-draft/examples/order-service.md

@@ -0,0 +1,92 @@
+# Worked example: order service events with four traps
+
+## Input given to the skill
+
+> We're moving fulfilment, loyalty and analytics off polling our order API and onto Kafka
+> events. Our brief is in order-events-brief.md. Can you draft the event contract so the three
+> teams can start building?
+
+The brief (in [`../evals/files/1/order-events-brief.md`](../evals/files/1/order-events-brief.md))
+asks for a `CreateShipment` event, an analytics feed "in one single global order", a
+`customerEmail` on every event "just in case", and an in-place rename of `total` to an integer
+`totalAmount` on the live `OrderPlaced`, which fulfilment consumes in production. Retention is
+7 days; nobody owns failed messages yet.
+
+## Output
+
+**What the contract decides**
+
+- `CreateShipment` becomes **`OrderPaid`**. The order service publishes the fact; the warehouse
+  decides to pick when it sees it. A command on a shared topic would make the order service own
+  the warehouse's workflow.
+- **No single global order across all orders.** Kafka orders messages only within a partition;
+  one partition for everything means one consumer at a time, and retries and dead-letter
+  redrives reorder it anyway. Instead, every event for one order arrives in order (the topic is
+  keyed by order id), and each event carries `occurredAt` and `orderRevision` so analytics can
+  sort across orders when it reads.
+- **`customerEmail` is dropped.** None of the three consumers uses it, and on Kafka it would
+  sit in every consumer's copy for the whole retention window. The delivery address stays, on
+  `OrderPaid` only, marked as personal data that fulfilment needs.
+- **`total` is not changed in place.** Fulfilment reads `OrderPlaced` in production and would
+  break on deploy. The new events go on a new topic, `orders.order-lifecycle.v1`: `OrderPlaced`
+  version 2 (with `totalAmount` in pence), `OrderPaid` and `OrderCancelled`. The existing
+  `orders` topic keeps publishing today's `OrderPlaced` unchanged until a date agreed with
+  fulfilment.
+
+**Decisions**
+
+| # | Decision | Choice | Why |
+|---|---|---|---|
+| 1 | Event names | `OrderPlaced`, `OrderPaid`, `OrderCancelled` | Facts in the order domain; replaces `CreateShipment` |
+| 2 | Topic and key | one topic, `orders.order-lifecycle.v1`, keyed by `orderId` | Paid and cancelled for one order must not race; one key means one partition, in order |
+| 3 | Ordering | per order only; no order across orders, no global order | Kafka's guarantee is per partition |
+| 4 | Producer publishing | each order's events published in commit order, from an outbox written in the same transaction | Without it the per-order promise in 2 is false |
+| 5 | Payload style | `OrderPlaced` and `OrderPaid` carry the order; `OrderCancelled` carries ids and who cancelled | Fulfilment picks and loyalty awards from `OrderPaid` alone; cancelling needs only the id |
+| 6 | Envelope | `eventId`, `eventType`, `eventVersion`, `occurredAt` (UTC, RFC 3339), `producer`, `correlationId`, `causationId` | Dedupe, routing, tracing; today's `placedAt` has no time zone |
+| 7 | Money | `totalAmount` as integer pence plus `currency` | Today's `42.50` is a decimal float |
+| 8 | Personal data | `customerEmail` dropped; `deliveryAddress` on `OrderPaid` only, marked | No consumer for the email; the address only once there is something to ship |
+| 9 | The `total` change | `OrderPlaced` v2 on the new topic; v1 on `orders` unchanged until sunset | A rename plus a type change is breaking; both publish during the window |
+| 10 | Delivery | at-least-once | Kafka redelivers on producer retries, rebalances and replays |
+| 11 | Retention and replay | 7 days; consumer groups can reset offsets within it | Platform default from the brief |
+| 12 | Dead letter | each consumer group parks a message after 5 failed attempts [assumption] on its own DLQ | Owner open; see below |
+
+**What consumers must do**
+
+1. Deduplicate on `eventId`. Fulfilment: a second `OrderPaid` for one order never starts a
+   second pick. Loyalty: award points keyed on the order id, so a repeat is a no-op.
+2. Apply an event only if its `orderRevision` is higher than the last one applied for that
+   order; drop it otherwise.
+3. Ignore fields and event types you don't recognise.
+4. Never rely on order across orders. Analytics sorts by `occurredAt`, then `orderRevision`.
+5. Park a message that fails 5 times on your DLQ, and watch it.
+6. Fulfilment: move from `orders` to `orders.order-lifecycle.v1` before the agreed date.
+
+**The AsyncAPI document** is saved as `asyncapi.json`
+(here: [`order-service.asyncapi.json`](order-service.asyncapi.json)). It passes a structural
+check: references resolve, every new message has the full envelope and a past-tense name, and
+each topic states its key, ordering, delivery, retention, replay and dead-letter handling. The
+only warnings are on the old `OrderPlaced` v1, documented as it runs today.
+
+**To confirm**
+
+- The date the old `OrderPlaced` stops on `orders`: order service team with fulfilment.
+- Who watches each dead-letter queue: order service team with each consumer team.
+- How the `orders` topic is keyed today: order service team.
+- Whether analytics needs more than 7 days of history to replay; if so, longer retention or an
+  archive: analytics with the platform team.
+- Whether loyalty awards points on `OrderPaid` (assumed) or `OrderPlaced`: loyalty.
+- Whether fulfilment reads `customerEmail` from today's event; if not, it can come off v1 now.
+
+## Checker output on the example
+
+```text
+AsyncAPI check: examples/order-service.asyncapi.json
+  2 channels, 4 messages, 2 operations
+WARN  (deprecated) message OrderPlacedV1: envelope fields missing from headers and payload: event id (eventId), event type (eventType), event version (eventVersion), occurred-at (occurredAt), producer (producer), correlation id (correlationId)
+WARN  message OrderPlacedV1: no causation id (causationId); consumers cannot tell which event caused this one
+WARN  message OrderPlacedV1: x-sunset is 'to agree with fulfilment', not a date; agree the date and list it as open until then
+PII (marked): message OrderPaid.payload.data.deliveryAddress
+PII (marked): message OrderPlacedV1.payload.customerEmail
+PII (marked): message OrderPlacedV1.payload.deliveryAddress
+Result: 0 failures, 3 warnings
+```

package/packs/solution-architect/skills/event-contract-draft/manifest.json

@@ -0,0 +1,25 @@
+{
+  "name": "event-contract-draft",
+  "version": "0.1.0",
+  "description": "Draft the contract for an event or message interface (Kafka topics, SNS/SQS, EventBridge, Pub/Sub, RabbitMQ, webhooks) as an AsyncAPI 3.0 document plus a short decisions page — past-tense event names, a required envelope with event id for deduplication, the partition key and the ordering it does and doesn't give, at-least-once delivery and how consumers stay idempotent, data minimisation with PII marked, additive-only versioning with dated deprecation, and retention, replay and dead-letter handling. Use when the user wants to define events, design a Kafka topic or message schema, write an AsyncAPI spec, agree what a producer publishes and what consumers must do, or version an event safely.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["api-contract-draft", "data-contract", "design-doc"],
+  "handoff": [
+    {
+      "to": "data-contract",
+      "when": "an analytics team or a trained model reads the topic as a dataset",
+      "purpose": "Add the freshness, completeness and field-semantics guarantees a dataset reader needs on top of the event contract.",
+      "fallback": "If data-contract is absent, add each analytics field's unit and meaning to the payload schema and list the freshness expectation under To confirm."
+    }
+  ],
+  "tags": ["asyncapi", "event-driven", "kafka", "messaging", "contract-first"],
+  "permissions": {
+    "network": [],
+    "commands": [],
+    "files": "named-paths",
+    "notes": "check_asyncapi.py reads the one JSON file it is given (or stdin) and writes a report only to the -o path the user names."
+  },
+  "model": { "tier": "standard", "rationale": "Contract drafting against the AsyncAPI shape with fixed rules on ordering, delivery and versioning; mid tier is enough." }
+}