skilldrop-cli 0.16.34 → 0.16.36

package/packs/product-manager/skills/lean-canvas/reference.md

@@ -0,0 +1,102 @@
+# lean-canvas reference
+
+Long-form material for the steps in `SKILL.md`. The canvas is Ash Maurya's adaptation of the
+Business Model Canvas (*Running Lean*); the interview rules follow Rob Fitzpatrick's *The Mom
+Test*.
+
+## The nine boxes, in the order to fill them
+
+| Box | What goes in | Common wrong entry |
+|---|---|---|
+| Problem | The top 1–3 problems, and how the early adopter copes today (existing alternatives) | A solution phrased as a problem: "no app for X" |
+| Customer segments | Who has the problem; the **early adopter** named separately, narrow enough to find by name | "Small businesses", "everyone who…" |
+| Unique value proposition | One sentence: why this, for the early adopter, instead of what they do today | A feature list |
+| Solution | The smallest thing that addresses each problem | A roadmap |
+| Channels | The paths to the early adopter, free and paid | Channels that reach the later segment |
+| Revenue streams | Price, who pays, how often | "Freemium" with no paid tier defined |
+| Cost structure | Cost to serve one customer, fixed costs, acquisition cost | Fixed costs only |
+| Key metrics | The 1–3 numbers that show the model works (activation, retention, paid conversion) | Downloads, page views |
+| Unfair advantage | What a funded competitor can't copy or buy within a year | A feature, "AI", "first mover", "passion" |
+
+**Internal products.** Revenue streams = the budget line or measured saving that keeps it
+funded. Customer = the team that has to change how it works; early adopter = the one team
+with the worst version of the problem and a lead who asked for help. Channel = how that team
+hears about and gets onto the tool (a mandate, a team lead, an existing workflow it plugs
+into). Unfair advantage can be real here: access to internal data or a mandate no vendor
+has. Still test whether the team will change its habits.
+
+## Grading evidence
+
+| Signal | Grade |
+|---|---|
+| Paid, pre-ordered, signed a letter of intent, or switched from a current tool | Behaviour — strongest |
+| Describes a recent, specific instance of the problem unprompted, and what it cost | Behaviour about the past — strong |
+| Built a workaround (spreadsheet, hired someone) | Behaviour — strong |
+| "I'd definitely use it", "great idea", survey interest | Opinion — weak, counts as assumption |
+| Industry statistic or report | Sizes the market; says nothing about this segment's willingness to pay |
+| Any of the above from a segment other than the early adopter | Counts as assumption for the early adopter |
+
+## Scoring risk
+
+| | Fatal (3) | Pivot (2) | Tune (1) |
+|---|---|---|---|
+| **High (3)** — no evidence, wrong segment, opinion only | 9 | 6 | 3 |
+| **Medium (2)** — right segment, few people or indirect | 6 | 4 | 2 |
+| **Low (1)** — observed behaviour, right segment | 3 | 2 | 1 |
+
+Ties: rank the assumption whose test is cheaper first; it clears the way for the rest.
+
+Why problem, customer and channel usually top the list: a wrong solution is fixed by
+rebuilding it, which a team can do in weeks. A wrong problem or an unreachable customer means
+the next build lands on nobody, and no amount of engineering moves it.
+
+## Test menu, cheapest first
+
+| Test | Proves wrong | Typical sample | Typical cost and time |
+|---|---|---|---|
+| Problem interview | The problem, the segment | 10–20 early adopters | $0–$200, 1–2 weeks |
+| Channel smoke test | The channel and its cost | $100–$500 of spend or one week of outreach on one channel | the spend, 1 week |
+| Landing page with a price | The UVP and the price | 100+ visitors from the stated channel | $100–$500, 1–2 weeks |
+| Concierge run (deliver it by hand) | The solution and retention | 3–10 customers | founder time, 2–4 weeks |
+| Pre-sale or letter of intent | Willingness to pay | 5–20 asks | $0, 2–4 weeks |
+| Wizard of Oz (looks automated, done by hand) | The solution at small volume | 10–30 uses | founder time, 2–4 weeks |
+
+A survey and "build an MVP and see" are not on the menu: the first measures opinion, the
+second costs months to learn what an interview learns in a week.
+
+## Setting the pass/fail line
+
+- **Write it before the test runs**, as a count: "fewer than 4 of 10". A line set after the
+  results arrive moves to fit them.
+- **Take it from the numbers when they exist.** Channel test fail line = the most a customer
+  can cost to acquire (lifetime margin ÷ 3 for a business that has to cover fixed costs;
+  lifetime margin at break-even). Landing-page fail line = the conversion that would
+  produce that cost per customer at the channel's cost per visitor.
+- **No numbers yet:** a problem interview passes when at least 4 in 10 describe a recent
+  instance unprompted; a pre-sale passes when at least 1 in 5 pays or signs.
+- **Say what failure changes:** which box is rewritten, and what the next test is.
+
+## Problem-interview rules
+
+1. Ask about the past, never the future. ✅ "When did that last happen? What did you do?"
+   ❌ "Would you use an app that…?"
+2. Don't pitch until the end, if at all. The moment the idea is described, people are polite.
+3. Ask what it cost them: time, money, a lost customer.
+4. Ask what they do about it today and what that costs. No workaround is a warning sign.
+5. Count who raised the problem **before** it was named, separately from who agreed once asked.
+
+Five-question script: "Walk me through your last [day/week/job]." / "What was the hardest
+part?" / "When did [problem area] last go wrong? What happened?" / "What did you do about
+it, and what did that cost?" / "What have you tried to fix it?"
+
+## What counts as an unfair advantage
+
+Counts: insider information, an existing audience or customer base, a network effect,
+a community, exclusive contracts or access, regulatory permission others lack, a team
+member whose name opens doors in this market, internal data or a mandate (internal products).
+
+Doesn't count: a feature, an algorithm, "AI", a patent pending on a feature, first-mover,
+better UX, lower price, hard work, passion. These go in Solution or UVP.
+
+"None yet" is the most common correct answer at this stage. Name a candidate the idea
+could grow into, if the input supports one.

package/packs/product-manager/skills/lean-canvas/scripts/unit_economics.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Unit-economics sanity check for a lean canvas.
+
+Stdlib only; runs on Python 3.9+. Computes, never estimates:
+
+  * contribution (gross margin) per customer per period, and as a % of price;
+  * customer lifetime in periods (given directly, or 1 / churn);
+  * lifetime gross margin (LTV) and LTV:CAC;
+  * CAC payback in periods, and whether it is longer than the lifetime;
+  * the most a customer can cost to acquire: at break-even (LTV) and at 3:1 (LTV / 3);
+  * break-even customers for the fixed costs, and the customers a stated
+    market can supply, when those are given.
+
+All money figures share one currency and one period (default "month"). Convert
+an annual price to monthly before passing it, or pass --period year with
+annual figures throughout.
+
+Usage:
+  python3 unit_economics.py --price 29 --variable-cost 6 --cac 400 \
+      --lifetime 9 --fixed 4300
+  python3 unit_economics.py --price 29 --variable-cost 6 --cac 400 --churn 0.11
+  python3 unit_economics.py --json inputs.json [-o out.md]
+  echo '{"price": 29, "variable_cost": 6, "cac": 400, "lifetime": 9}' | \
+      python3 unit_economics.py --json -
+
+JSON keys mirror the flags: price, variable_cost, cac, lifetime, churn,
+fixed, market_customers, period. Flags given on the command line override
+the JSON.
+
+Exit codes: 0 ok, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+KEYS = ("price", "variable_cost", "cac", "lifetime", "churn", "fixed", "market_customers")
+
+
+def fail(msg: str) -> None:
+    print(f"error: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def load_json(path: str) -> dict:
+    try:
+        if path == "-":
+            data = json.load(sys.stdin)
+        else:
+            with open(path, encoding="utf-8") as fh:
+                data = json.load(fh)
+    except FileNotFoundError:
+        fail(f"no such file: {path}")
+    except json.JSONDecodeError as exc:
+        fail(f"not valid JSON ({exc})")
+    if not isinstance(data, dict):
+        fail("JSON input must be one object")
+    return data
+
+
+def number(name: str, value, minimum: float = 0.0, allow_equal: bool = True):
+    if value is None:
+        return None
+    try:
+        val = float(value)
+    except (TypeError, ValueError):
+        fail(f"{name} must be a number, got {value!r}")
+    if val < minimum or (not allow_equal and val == minimum):
+        op = ">=" if allow_equal else ">"
+        fail(f"{name} must be {op} {minimum:g}, got {val:g}")
+    return val
+
+
+def money(x: float) -> str:
+    return f"{x:,.2f}"
+
+
+def compute(inp: dict) -> tuple[list[str], list[str]]:
+    period = str(inp.get("period") or "month")
+    price = number("price", inp.get("price"), 0.0, allow_equal=False)
+    if price is None:
+        fail("price is required (per customer per period)")
+    vcost = number("variable_cost", inp.get("variable_cost")) or 0.0
+    cac = number("cac", inp.get("cac"))
+    lifetime = number("lifetime", inp.get("lifetime"), 0.0, allow_equal=False)
+    churn = inp.get("churn")
+    fixed = number("fixed", inp.get("fixed"))
+    market = number("market_customers", inp.get("market_customers"))
+
+    if churn is not None:
+        churn = number("churn", churn, 0.0, allow_equal=False)
+        if churn > 1:
+            if churn <= 100:
+                churn = churn / 100.0  # "11" meaning 11%
+            else:
+                fail("churn must be a fraction (0.11) or a percent (11)")
+        if lifetime is None:
+            lifetime = 1.0 / churn
+
+    lines: list[str] = []
+    flags: list[str] = []
+
+    margin = price - vcost
+    margin_pct = margin / price * 100
+    lines.append(f"Price per customer per {period}: {money(price)}")
+    if inp.get("variable_cost") is None:
+        lines.append(f"Variable cost per customer per {period}: not given, treated as 0")
+        flags.append("No cost to serve was given, so every margin figure here is an upper bound.")
+    else:
+        lines.append(f"Variable cost per customer per {period}: {money(vcost)}")
+    lines.append(f"Contribution per customer per {period}: {money(margin)} ({margin_pct:.1f}% gross margin)")
+    if margin <= 0:
+        flags.append(f"Each customer costs more to serve than they pay ({money(margin)} per {period}). No volume fixes this.")
+
+    ltv = None
+    if lifetime is not None:
+        src = f"1 / churn of {churn * 100:.1f}%" if churn is not None and inp.get("lifetime") is None else "as given"
+        lines.append(f"Customer lifetime: {lifetime:.1f} {period}s ({src})")
+        ltv = margin * lifetime
+        lines.append(f"Lifetime contribution (LTV): {money(ltv)}")
+
+    if cac is not None:
+        lines.append(f"Customer acquisition cost (CAC): {money(cac)}")
+        if margin > 0:
+            payback = cac / margin
+            lines.append(f"CAC payback: {payback:.1f} {period}s")
+            if lifetime is not None and payback > lifetime:
+                flags.append(
+                    f"CAC payback ({payback:.1f} {period}s) is longer than the customer lifetime "
+                    f"({lifetime:.1f} {period}s): every acquired customer loses {money(cac - ltv)}."
+                )
+        if ltv is not None:
+            ratio = ltv / cac if cac > 0 else float("inf")
+            lines.append(f"LTV:CAC: {ratio:.2f}" if cac > 0 else "LTV:CAC: no acquisition cost given as 0")
+            if cac > 0 and ratio < 1:
+                flags.append(f"LTV:CAC is {ratio:.2f}: acquisition destroys money before fixed costs.")
+            elif cac > 0 and ratio < 3:
+                flags.append(f"LTV:CAC is {ratio:.2f}, under the 3:1 most subscription businesses need to cover fixed costs.")
+
+    if ltv is not None and ltv > 0:
+        lines.append(f"Most a customer can cost to acquire: {money(ltv)} at break-even, {money(ltv / 3)} at 3:1")
+
+    if fixed is not None:
+        lines.append(f"Fixed costs per {period}: {money(fixed)}")
+        if margin > 0:
+            be = fixed / margin
+            be_whole = int(be) if be == int(be) else int(be) + 1
+            lines.append(f"Break-even customers (active at once): {be_whole:,}")
+            if market is not None:
+                lines.append(f"Customers the stated market holds: {int(market):,}")
+                if be_whole > market:
+                    flags.append(
+                        f"Break-even needs {be_whole:,} active customers but the stated market holds {int(market):,}."
+                    )
+                else:
+                    share = be_whole / market * 100
+                    lines.append(f"Break-even share of the stated market: {share:.1f}%")
+                    if share >= 25:
+                        flags.append(
+                            f"Break-even needs {share:.0f}% of the stated market as paying customers at the same time."
+                        )
+            if cac is not None and ltv is not None and ltv <= cac:
+                flags.append("Break-even customers cannot be reached through paid acquisition at this CAC: each one adds a loss.")
+
+    missing = [k for k in ("variable_cost", "cac", "lifetime/churn", "fixed")
+               if (k == "lifetime/churn" and lifetime is None)
+               or (k != "lifetime/churn" and inp.get(k) is None)]
+    if missing:
+        lines.append("Not computed (input missing): " + ", ".join(missing))
+    return lines, flags
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Unit-economics sanity check for a lean canvas.")
+    ap.add_argument("--json", metavar="PATH", help="JSON object of inputs, or - for stdin")
+    ap.add_argument("--price", help="price per customer per period")
+    ap.add_argument("--variable-cost", dest="variable_cost", help="cost to serve one customer per period")
+    ap.add_argument("--cac", help="cost to acquire one paying customer")
+    ap.add_argument("--lifetime", help="average customer lifetime in periods")
+    ap.add_argument("--churn", help="churn per period, as 0.11 or 11")
+    ap.add_argument("--fixed", help="fixed costs per period")
+    ap.add_argument("--market-customers", dest="market_customers", help="customers the stated market holds")
+    ap.add_argument("--period", help='period label, default "month"')
+    ap.add_argument("-o", "--output", help="write the report to this path instead of stdout")
+    args = ap.parse_args()
+
+    inp: dict = load_json(args.json) if args.json else {}
+    unknown = set(inp) - set(KEYS) - {"period"}
+    if unknown:
+        fail("unknown JSON keys: " + ", ".join(sorted(unknown)))
+    for key in KEYS + ("period",):
+        val = getattr(args, key)
+        if val is not None:
+            inp[key] = val
+
+    lines, flags = compute(inp)
+    out = ["Unit economics", ""] + [f"- {ln}" for ln in lines]
+    out += ["", "Where the numbers don't close:" if flags else "Where the numbers don't close: none found."]
+    out += [f"- {f}" for f in flags]
+    text = "\n".join(out) + "\n"
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(text)
+    else:
+        sys.stdout.write(text)
+
+
+if __name__ == "__main__":
+    main()

package/packs/solution-architect/skills/api-contract-draft/SKILL.md

@@ -29,7 +29,7 @@ Produces the contract *before* the code — a valid OpenAPI 3.1 document two tea
    3. **Open questions** — the unknowns that block freezing the contract, each with who can answer it
    Start from [`templates/openapi-skeleton.yaml`](templates/openapi-skeleton.yaml).
 
-6. **For event/queue contracts** (the brief says "publish", "consume", "webhook out"): same discipline, AsyncAPI-shaped — channel name, payload schema with the same typing rigor, delivery semantics stated (at-least-once is the default; say it), and the consumer-retry/DLQ expectation in the channel description.
+6. **For event/queue contracts** (the brief says "publish", "consume", "webhook out"): hand the event side to `event-contract-draft`, which owns event naming, the envelope, ordering, delivery and versioning. When the request mixes both, draft the HTTP side here and say which events it leaves to that contract.
 
 ## Useful references in this skill
 
@@ -50,12 +50,12 @@ Produces the contract *before* the code — a valid OpenAPI 3.1 document two tea
 - ✅ Designing a new API or new resource before implementation
 - ✅ Frontend and backend (or two teams) need a contract to build against in parallel
 - ✅ A story from `user-story-splitter` whose slice is "expose X over the API"
-- ✅ Drafting the webhook/event contract a partner will consume
 
 ## When NOT to use this skill
 
 - ❌ Documenting an API that already exists — that's `guide-builder` (reference archetype)
 - ❌ Choosing REST vs GraphQL vs gRPC — this skill starts after that choice is made
+- ❌ An event, message or webhook contract — that's `event-contract-draft`
 - ❌ Reviewing a contract someone else drafted — `doc-critique` or `council-review`
 - ❌ Generating server/client code from the spec — hand the frozen contract to the codegen tool
 

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

@@ -1,11 +1,33 @@
 {
   "name": "api-contract-draft",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML. Use when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.",
   "entrypoint": "SKILL.md",
-  "deps": { "npm": [], "pip": [] },
-  "env": { "required": [], "optional": [] },
-  "related": ["council-review", "doc-critique", "guide-builder", "user-story-splitter"],
-  "tags": ["api-design", "openapi", "contract-first", "rest", "swagger", "asyncapi"],
-  "model": { "tier": "standard", "rationale": "Schema synthesis against fixed conventions. The resource modeling needs judgment; the conventions bound it. Escalate via ambiguous-input on contested multi-team contracts." }
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "council-review",
+    "doc-critique",
+    "guide-builder",
+    "user-story-splitter",
+    "event-contract-draft"
+  ],
+  "tags": [
+    "api-design",
+    "openapi",
+    "contract-first",
+    "rest",
+    "swagger",
+    "asyncapi"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Schema synthesis against fixed conventions. The resource modeling needs judgment; the conventions bound it. Escalate via ambiguous-input on contested multi-team contracts."
+  }
 }

package/packs/solution-architect/skills/event-contract-draft/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: event-contract-draft
+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.
+---
+
+# event-contract-draft
+
+Produces the contract for an asynchronous interface before producer and consumers build
+against it: an AsyncAPI 3.0 document and a one-page decisions record. Request/response HTTP
+APIs are `api-contract-draft`; a dataset's schema and quality SLAs for analytics readers are
+`data-contract`; the system design that decides events are the right tool is `design-doc`.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
+- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
+- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
+- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
+- **For this skill:** When the request asks for something an event contract can't promise (global order, exactly-once, "change it in place", "include it just in case"), the first lines say no, why, and what the contract offers instead. Building the unsafe version quietly is the failure this skill exists to prevent.
+
+1. **Size the reply to the ask.** A question about one rule ("is ordering guaranteed if we key
+   by paymentId?") gets a direct answer in a few lines: yes or no, why, the fix. No AsyncAPI
+   document. A request to define events gets the full contract (step 11).
+
+2. **List the facts, the producer and the consumers.** For each consumer, write what it does
+   with each event; that line decides payload size and justifies every field. Ask at most 2
+   questions, spent on who consumes and what they do with it, and which broker. Missing broker
+   → write broker-neutral with a Kafka binding, tagged `[assumption]`.
+
+3. **Name events as facts, past tense, in the producer's domain.** One event type per message
+   schema.
+   - ✅ `OrderPaid` — ❌ `CreateShipment`. A command tells another team what to do and couples
+     the producer to the warehouse's process; the warehouse decides to pick when it sees
+     `OrderPaid`. If one named receiver must act, that is a command on the receiver's queue,
+     outside this contract; say so.
+   - ✅ `OrderPlaced`, `OrderCancelled` — ❌ `OrderEvent` with a `status` field. A generic
+     event makes every consumer parse a union and breaks them all when a status is added.
+   - ✅ `OrderDeliveryAddressChanged` — ❌ `OrderUpdated` when the business fact has a name.
+
+4. **Decide notification or event-carried state per event, with the reason.** Notification =
+   ids plus a link; consumers call back. Event-carried state = the fields named consumers act
+   on, so they never call back. ✅ *"`OrderPaid` carries lines and address: fulfilment picks
+   without calling the order API."* ❌ The whole order aggregate on every event "for
+   flexibility". Table in [`reference.md`](reference.md).
+
+5. **Put the envelope on every message, all required:** event id, event type, event version,
+   occurred-at (UTC, RFC 3339, `format: date-time`), producer, correlation id; causation id
+   too. Domain fields go under `data`, with a per-entity revision (`orderRevision`) that
+   increases on each change. ❌ `"placedAt": "2026-10-19 14:03:11"` — no zone, not RFC 3339.
+   Money is integer minor units plus currency: ❌ `"total": 42.50`.
+
+6. **State delivery, ordering and duplicates per channel.**
+   - **Delivery is at-least-once** unless the broker and the consumer prove otherwise.
+     Consumers deduplicate on the event id or apply only a higher revision; name which, per
+     consumer. ✅ *"Loyalty awards points keyed on (orderId, reason); a second OrderPaid is a
+     no-op."* ❌ "Exactly-once delivery" in the description.
+   - **Ordering exists only per partition key.** Name the key, what it orders, and what it
+     doesn't. ✅ *"Keyed by orderId: one order's events arrive in order. No order across
+     orders, no global order."* Events whose relative order matters (`OrderPaid`,
+     `OrderCancelled`) share one channel and one key; on two topics they race.
+   - **A global-order request is declined.** One partition means one consumer at a time, and
+     retries and dead-letter redrives reorder it anyway. Offer what the reader needs:
+     per-entity order plus `occurredAt` and the revision, sorted at read time.
+   - **The producer publishes each entity's events in commit order** (an outbox written in
+     the same transaction), or the per-key promise is false.
+   - **Webhooks** have no ordering: receivers use the revision. Sign the raw body (HMAC) with
+     a timestamp inside the signature so receivers reject replays; state the retry schedule,
+     its cap, and where deliveries that keep failing go.
+
+7. **Minimise the data.** Every field names the consumer that uses it; no consumer, no field.
+   ❌ `customerEmail` "just in case": it sits in every consumer's log and replay for the whole
+   retention window and cannot be recalled. Personal data a consumer does need stays and gets
+   `x-pii` naming that consumer (✅ `deliveryAddress` for fulfilment). Card numbers never go on
+   an event, marked or not; send a payment reference or the last four digits.
+
+8. **Version additively; break only with a new version and a date.** Within a version only
+   optional fields are added; consumers ignore unknown fields, so payload schemas stay open
+   (no `additionalProperties: false`). A rename, type or unit change, removal, new required
+   field or key change is breaking. ❌ Renaming `total` in place while a consumer reads it in
+   production. ✅ Add `totalMinor` beside `total`, publish both, mark `total` deprecated with a
+   sunset date; or publish `v2` on a new channel alongside `v1` for a dual-publish window. The
+   sunset date comes from the input or is "to agree with <consumer>"; never invent one. New
+   event types on a live topic whose consumers assume one type break those consumers: put
+   them on a new channel or confirm the consumers skip unknown types.
+
+9. **State retention, replay and dead-letter on every channel.** How long messages are kept
+   (from the input or `[assumption]`), whether consumers can replay and from where, what goes
+   to the DLQ after how many attempts, and who watches it. An unnamed DLQ owner goes under "To
+   confirm", not a made-up team. Broker specifics in [`reference.md`](reference.md).
+
+10. **Write the contract.** Start from
+    [`templates/asyncapi-skeleton.json`](templates/asyncapi-skeleton.json); emit JSON (the
+    check below reads JSON only). Channel facts go in `x-partition-key`, `x-ordering`,
+    `x-delivery`, `x-retention`, `x-replay`, `x-dead-letter`; consumer duties in
+    `info.description`. Then run the check and fix every FAIL:
+
+    ```bash
+    # Claude Code
+    python3 "${CLAUDE_SKILL_DIR}/scripts/check_asyncapi.py" asyncapi.json
+    # Other IDEs (from the skill folder)
+    python3 scripts/check_asyncapi.py asyncapi.json
+    ```
+
+    It checks AsyncAPI 3.x structure, `$ref`s, past-tense names, the envelope in every message,
+    one type per schema, unmarked personal data, closed schemas, deprecation dates, and each
+    channel's key, ordering, delivery, retention, replay and DLQ notes. When it can't run, say
+    the document is unchecked. Never claim a check that didn't run.
+
+11. **Reply in this order:**
+    1. **What the contract decides**, 3–6 lines, leading with every pushback from steps 3–9.
+    2. **Decisions**: a table of decision, choice, why (shape in [`reference.md`](reference.md)).
+    3. **What consumers must do**: numbered, at most 6: dedupe, ignore unknown fields, revision
+       check, no cross-key order, DLQ duty, the migration they owe and by when.
+    4. **The AsyncAPI document**, saved as `asyncapi.json` when files can be written, inline
+       otherwise; then one line on the check result.
+    5. **To confirm**: each open item with who can answer it.
+
+**Non-interactive runs** (subagent, CI, headless): a missing broker, retention, consumer
+detail or sunset date becomes a tagged `[assumption]` or a "To confirm" line, and the contract
+ships. No producer or no event at all emits `BLOCKED: need the producing service and what
+happens in it that others react to`.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — envelope fields and CloudEvents mapping, notification vs state, safe vs breaking changes, broker ordering/delivery/retention facts, consumer idempotency patterns, the `x-` extensions, decisions page shape
+- [`templates/asyncapi-skeleton.json`](templates/asyncapi-skeleton.json) — valid AsyncAPI 3.0 starting point with envelope, two messages and every channel extension
+- [`scripts/check_asyncapi.py`](scripts/check_asyncapi.py) — the structural and rule check (stdlib only; JSON input; exit 1 on failures)
+- [`examples/order-service.md`](examples/order-service.md) — worked example: an order service brief with four traps, and the contract that answers it
+
+## Quality bar
+
+- **Every event name is a past-tense fact** in the producer's domain, one type per schema.
+- **Every message has the full envelope, required**, with a stable event id for deduplication.
+- **Every channel names its key, the order it gives and the order it doesn't.** No global order.
+- **Each consumer's idempotency is stated**: dedupe on id, revision check, or a natural key.
+- **Every field has a consumer**; personal data that stays is marked; nothing "just in case".
+- **Breaking changes go through a new field or version** with a deprecation date that came from the input or is listed as open.
+- **Retention, replay and dead-letter are stated per channel**, with the DLQ owner named or open.
+- **The check result is reported only if it ran**, and the document has no FAIL.
+- **Nothing invented**: no team names, dates, volumes or retention the input didn't give, except as `[assumption]`.
+
+## When to use this skill
+
+- ✅ Defining the events a service publishes, before consumers build against them
+- ✅ Designing a Kafka topic, SNS/SQS, EventBridge, Pub/Sub or RabbitMQ message contract
+- ✅ Changing a live event's schema without breaking its consumers
+- ✅ A webhook contract partners will receive
+- ✅ "Is ordering / exactly-once / dedup guaranteed if we do X?" about a message interface
+
+## When NOT to use this skill
+
+- ❌ A request/response HTTP API — `api-contract-draft`
+- ❌ A table, dataset or analytics stream's schema, freshness and quality SLAs — `data-contract`
+- ❌ Deciding whether the system should be event-driven at all, or its components — `design-doc`
+
+## Anti-patterns to avoid
+
+- ❌ **Commands dressed as events.** `CreateShipment` on a topic makes the order service own the warehouse's workflow.
+- ❌ **Promising global order** or exactly-once because someone asked. Brokers give per-key order and at-least-once.
+- ❌ **No event id**, so consumers dedupe on a hash of the payload and double-count the legitimate repeat.
+- ❌ **Related events on separate topics** whose order then races: `OrderCancelled` overtakes `OrderPaid`.
+- ❌ **The "just in case" field.** Personal data with no consumer, kept in every log for the retention window.
+- ❌ **In-place breaking change** to a live event, "so there's one version to maintain". Fulfilment breaks at deploy.
+- ❌ **`additionalProperties: false`** on payloads, which turns every additive change into a breaking one.
+- ❌ **A DLQ nobody owns.** Messages land there and the business notices weeks later.

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

@@ -0,0 +1,38 @@
+[
+  {
+    "query": "Write the AsyncAPI spec for the order events our service publishes to Kafka",
+    "should_trigger": true
+  },
+  {
+    "query": "Define the message schema, envelope and partition key for our payment events topic",
+    "should_trigger": true
+  },
+  {
+    "query": "We need to rename a field on a live SNS/SQS event without breaking the consumers. How do we version it?",
+    "should_trigger": true
+  },
+  {
+    "query": "Draft the EventBridge event contract for InvoicePaid, including what consumers have to do about duplicates",
+    "should_trigger": true
+  },
+  {
+    "query": "If we key our Kafka topic by customerId, is ordering guaranteed for each order?",
+    "should_trigger": true
+  },
+  {
+    "query": "Draft the OpenAPI spec for the orders REST API: create, fetch and list orders",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a data contract for the orders table the analysts query in the warehouse, with freshness and completeness SLAs",
+    "should_trigger": false
+  },
+  {
+    "query": "Define the data contract for the clickstream topic that feeds the lakehouse, with null-rate and volume checks",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a design doc for moving the order service from polling to an event-driven architecture",
+    "should_trigger": false
+  }
+]