skilldrop-cli 1.3.0 → 1.5.0

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

@@ -1,211 +0,0 @@
-#!/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 if market else 0.0  # 0 needed of a 0 market
-                    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/sre-oncall/loops/operate/LOOP.md

@@ -1,84 +0,0 @@
----
-name: operate
-description: Take a shipped service through detection, response, and learning — instrument it, write the runbook, communicate the incident, then feed the postmortem's deltas back into the runbook. Use when the user is preparing to run a service, is in an incident, or is writing a postmortem.
----
-
-# operate
-
-The only loop whose failures are **irreversible and live**. The other four can be re-run at
-the cost of time; this one runs while real users are affected. Its feedback edge is the point:
-`postmortem-generator` emits runbook deltas phrased as edits, and those go straight back into
-`document`. An incident that changes no procedure has not been learned from.
-
-## Stages
-
-| # | Stage | Type | Skills | Gate |
-|---|---|---|---|---|
-| 1 | `instrument` | generate | [`observability-plan`](../../skills/observability-plan/SKILL.md) | — |
-| 2 | `document` | generate | [`runbook-generator`](../../skills/runbook-generator/SKILL.md) | — |
-| 3 | `respond` | generate | [`incident-comms`](../../skills/incident-comms/SKILL.md) | — |
-| 4 | `learn` | verify | [`postmortem-generator`](../../skills/postmortem-generator/SKILL.md) | **G4** human |
-
-## How to run this loop
-
-1. **Instrument first.** `observability-plan` decides what is measured and what pages a human.
-   You cannot respond to what you never detected, and you cannot write a runbook entry for an
-   alert that does not exist.
-2. **Write the runbook per alert.** Each alert the previous stage defined maps to a
-   `runbook-generator` entry. An alert with no procedure wakes someone who then has to think.
-3. **Respond to the audience the incident actually has.** `incident-comms` is staged —
-   detect, mitigate, resolve — and the stage determines the message. Writing a resolution
-   update during mitigation is the most common error here.
-4. **Learn at G4.** `postmortem-generator` analyses blamelessly and ends with runbook deltas.
-   A human signs off that the incident is closed. `REVISE` returns to `document`: the deltas
-   are the loop's output, and applying them is what closes it.
-
-Entering mid-loop is normal and expected. An incident starts at `respond`; a new service
-starts at `instrument`. Do not replay earlier stages for their own sake.
-
-## Verdicts
-
-Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json). G4 emits `PROCEED`,
-`PROCEED WITH CONDITIONS`, `REVISE`, or `BLOCKED`. `PROCEED WITH CONDITIONS` means the
-incident is closed but named follow-ups are outstanding — they travel with the postmortem.
-
-## Non-interactive runs
-
-Never fabricate incident facts — timings, impact, customer counts, root cause. When the
-timeline is incomplete, emit `BLOCKED: need <the missing facts>` and name them. A confident
-postmortem built on guessed impact is worse than no postmortem.
-
-## When a stage's skill is not installed
-
-Name the missing skill and skilldrop as its source, do the minimal inline version, and record
-the stage as degraded. During a live incident, prefer the degraded inline version over
-stopping to install anything.
-
-## Run log (opt-in)
-
-Only when the environment variable `SKILLDROP_LOOP_LOG` is set to a file path: after each
-gate's verdict, append one JSON line to that file. Nothing else is recorded, and nothing is
-sent anywhere. When the variable isn't set, or you can't read it, skip this section.
-
-```bash
-printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"operate","stage":"learn","gate":"G4","verdict":"PROCEED","round":1}' >> "$SKILLDROP_LOOP_LOG"
-```
-
-Fields: `ts` (UTC), `loop`, `stage`, `gate` (`null` for a stage without one), `verdict` (the
-gate's exact word), and `round` (1 for the first attempt, counting returns under the cap).
-`skilldrop loop-stats` summarises the file: which gates pass first time, which loop back, and
-which end in `BLOCKED`.
-
-## Quality bar
-
-- **Every alert has a runbook entry.** An alert that pages someone with no procedure is an interruption, not a signal.
-- **The postmortem ends in runbook deltas.** Analysis with no procedural change is a story about an outage.
-- **Comms match the incident's actual stage.** Detect, mitigate, and resolve have different audiences and different truths.
-- **Blameless means blameless.** Naming a person is a defect in the postmortem; naming a missing guardrail is the point.
-
-## Anti-patterns to avoid
-
-- ❌ **Writing the runbook before the observability plan.** Procedures for alerts that do not exist, and none for the alerts that do.
-- ❌ **Skipping `learn` because the incident was small.** Small incidents are where the cheap runbook deltas are.
-- ❌ **Guessing impact numbers to finish the postmortem.** State the gap; a postmortem's value is entirely in its accuracy.
-- ❌ **Replaying `instrument` during a live incident.** Enter at `respond`; the loop is not a checklist to complete in order.

package/packs/sre-oncall/loops/operate/evals/eval_queries.json

@@ -1,30 +0,0 @@
-[
-  {
-    "query": "write the postmortem for last night's incident",
-    "should_trigger": true
-  },
-  {
-    "query": "run the operate loop on this service",
-    "should_trigger": true
-  },
-  {
-    "query": "what should we alert on and what's the runbook?",
-    "should_trigger": true
-  },
-  {
-    "query": "we're in an incident — what do I tell customers?",
-    "should_trigger": true
-  },
-  {
-    "query": "implement the fix for this bug",
-    "should_trigger": false
-  },
-  {
-    "query": "design the retry architecture",
-    "should_trigger": false
-  },
-  {
-    "query": "draft the PRD for this feature",
-    "should_trigger": false
-  }
-]

package/packs/sre-oncall/loops/operate/evals/evals.json

@@ -1,25 +0,0 @@
-{
-  "loop_name": "operate",
-  "evals": [
-    {
-      "id": "postmortem-must-produce-runbook-deltas",
-      "prompt": "Run the operate loop. Our rate limiter alert fired last night — a customer's retry loop hammered the API for 40 minutes.",
-      "assertions": [
-        "Enters at `respond`, not at `instrument` — an incident does not replay earlier stages",
-        "Stages the communication (detect / mitigate / resolve) and matches the message to the stage the incident is in",
-        "Produces a blameless postmortem that names missing guardrails, never people",
-        "Ends in concrete runbook deltas phrased as before/after edits",
-        "Routes those deltas back to `document` via G4's revise edge rather than treating the postmortem as terminal"
-      ]
-    },
-    {
-      "id": "refuses-to-guess-incident-facts",
-      "prompt": "Write the postmortem for last night's outage. I don't have the exact timeline or customer impact numbers yet.",
-      "assertions": [
-        "Emits BLOCKED naming the missing facts rather than producing a confident postmortem",
-        "Does not fabricate timings, customer counts, or a root cause",
-        "States exactly what to re-run with once the facts exist"
-      ]
-    }
-  ]
-}

package/packs/sre-oncall/loops/operate/loop.json

@@ -1,41 +0,0 @@
-{
-  "$comment": "RFC-0028. The only loop whose failures are irreversible and live. Its feedback edge is real and already documented in the repo: postmortem-generator emits runbook deltas phrased as edits for runbook-generator.",
-  "name": "operate",
-  "version": "0.3.0",
-  "description": "Take a shipped service through detection, response, and learning — instrument it, write the runbook, communicate the incident, then feed the postmortem's deltas back into the runbook. Use when the user is preparing to run a service, is in an incident, or is writing a postmortem.",
-  "entrypoint": "LOOP.md",
-  "kind": "loop",
-  "cap": 3,
-  "stages": [
-    {
-      "id": "instrument",
-      "type": "generate",
-      "intent": "Decide what is measured and what pages a human. You cannot respond to what you never detected.",
-      "skills": ["observability-plan"]
-    },
-    {
-      "id": "document",
-      "type": "generate",
-      "intent": "Write the procedure the on-call follows at 3am, per alert the previous stage defined.",
-      "skills": ["runbook-generator"]
-    },
-    {
-      "id": "respond",
-      "type": "generate",
-      "intent": "Communicate during the incident, to the audience that needs it, at the stage the incident is actually in.",
-      "skills": ["incident-comms"]
-    },
-    {
-      "id": "learn",
-      "type": "verify",
-      "intent": "Analyse blamelessly and emit runbook deltas. An incident that changes no procedure has not been learned from.",
-      "skills": ["postmortem-generator"],
-      "gate": {
-        "id": "G4",
-        "kind": "human",
-        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
-        "revise_to": "document"
-      }
-    }
-  ]
-}