skilldrop-cli 0.2.0

package/skills/brief-intake/templates/brief-runbook.md

@@ -0,0 +1,44 @@
+# Brief: Runbook
+
+> Target downstream skill: `runbook-generator`
+
+## Service
+- **Name:** {service-name} [explicit|implied|inferred|missing]
+- **One-line purpose:** {what it does} [explicit|implied|inferred|missing]
+> "{verbatim snippet}"
+
+## Owners
+- **Team:** {team name — role-based, not individual} [explicit|implied|inferred|missing]
+- **Primary on-call rotation:** {rotation name / PagerDuty schedule} [explicit|implied|inferred|missing]
+- **Escalation chain:** {who's next if primary is unavailable} [explicit|implied|inferred|missing]
+
+## Tech stack
+- **Language / runtime:** {e.g. Go 1.22, Python 3.12} [explicit|implied|inferred|missing]
+- **Storage:** {e.g. Postgres 15, Redis, S3} [explicit|implied|inferred|missing]
+- **Message brokers / queues:** {e.g. Kafka, SQS — or `n/a`} [explicit|implied|inferred|missing]
+- **External dependencies:** {APIs, vendor services} [explicit|implied|inferred|missing]
+
+## Deployment surface
+- **Platform:** {Kubernetes / ECS / Lambda / VMs} [explicit|implied|inferred|missing]
+- **Namespace / cluster / region:** {coordinates} [explicit|implied|inferred|missing]
+- **Deploy mechanism:** {GitHub Actions / ArgoCD / manual / …} [explicit|implied|inferred|missing]
+
+## Known failure modes (the "common 5")
+- {Failure 1 — symptom + suspected cause if known} [explicit|implied|inferred|missing]
+- {Failure 2}
+- {Failure 3}
+- {Failure 4}
+- {Failure 5}
+
+## Existing dashboards / alerts referenced in source
+- {Dashboard URL or name} [explicit|implied|inferred|missing]
+- {Alert name → page severity}
+
+## SLOs (if any)
+- {Metric → target, e.g. "p99 latency < 200ms"} [explicit|implied|inferred|missing]
+
+---
+
+## 🚩 Missing for downstream
+- {field: why it matters}
+- {e.g. "No owner team — runbook-generator refuses to draft without current ownership"}

package/skills/brief-intake/templates/brief-tech-comparison.md

@@ -0,0 +1,38 @@
+# Brief: Tech Comparison
+
+> Target downstream skill: `tech-comparison-matrix`
+
+## The question
+{One sentence — what's being chosen and what for. e.g. "Pick a primary OLTP datastore for the new checkout service."} [explicit|implied|inferred|missing]
+> "{verbatim snippet}"
+
+## Candidates
+- **{Candidate A}** — {one-line positioning if source has it} [explicit|implied|inferred|missing]
+- **{Candidate B}**
+- **{Candidate C}**
+
+## Evaluation criteria (with weights if source implies them)
+- **{Criterion 1}** ({weight if known}) — {what "good" looks like} [explicit|implied|inferred|missing]
+- **{Criterion 2}**
+- **{Criterion 3}**
+- **{Criterion 4}**
+- **{Criterion 5}**
+
+## Constraints / non-negotiables
+- {Existing estate, e.g. "must run on AWS"} [explicit|implied|inferred|missing]
+- {Team skills, e.g. "team has 5 years of Postgres"}
+- {Compliance, e.g. "data must stay in eu-west-1"}
+
+## Workload profile
+- **Read/write ratio:** {ratio} [explicit|implied|inferred|missing]
+- **Scale targets:** {QPS, data volume, growth} [explicit|implied|inferred|missing]
+- **Consistency needs:** {strong / eventual / tunable} [explicit|implied|inferred|missing]
+
+## Tentative leaning (if stated)
+{"Source seems to favour X because Y" — flag so matrix can be honest about bias} [explicit|implied|inferred|missing]
+
+---
+
+## 🚩 Missing for downstream
+- {e.g. "Only 1 candidate captured — comparison needs ≥2"}
+- {e.g. "No evaluation criteria — matrix will default to a generic set"}

package/skills/bug-triage/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: bug-triage
+description: Turn a vague bug report (Slack message, support ticket, "it's broken on mobile sometimes") into an actionable ticket — searchable symptom title, numbered repro steps from a clean state, expected vs actual, severity separated from priority, evidence tagged reported-vs-verified, and labeled hypotheses instead of root-cause guesses. Use when the user wants to triage a bug, write up a bug report, turn a complaint into a ticket, or make a flaky issue actionable.
+---
+
+# bug-triage
+
+Converts the bug report someone *sent* into the ticket an engineer can *start* — without a round of "can you clarify?" first. The discipline: separate what was reported from what's verified, separate severity from priority, and label every guess as a guess. Triage shapes the work; fixing it is `feature-implement-loop` (or a human) downstream.
+
+## How to respond
+
+1. **Ingest the raw report** — Slack thread, support ticket, user email, a teammate's "X is broken". Mine it for the six ticket fields before asking anything. Then ask **at most 3 questions, ranked by diagnostic value** — the answers that most shrink the search space (exact error text, when it last worked, does it reproduce on a second account/device). Everything unconfirmed proceeds with a tag, not a guess.
+
+2. **One bug per ticket.** A report with three symptoms becomes three tickets (or one ticket + a "split out" note naming the others). Multi-symptom tickets close half-fixed.
+
+3. **Write the title as symptom + condition, searchable.** ✅ *"Checkout button stays disabled after removing an expired coupon (Safari 17, guest cart)"* — ❌ *"Checkout broken"*, ❌ *"Coupon bug"*. Six months from now someone greps tickets for "disabled checkout" — that's who the title is for.
+
+4. **Tag every claim `[reported]` or `[verified]`.** What the reporter says happened vs what was confirmed by logs, a screenshot, or your own reproduction. Triage that presents `[reported]` as fact sends an engineer chasing a description instead of a behavior.
+
+5. **Number the repro steps from a clean state** — fresh session, named test account, stated starting URL — each step an observable action, ending in the failure. If reproduction is unknown, the ticket says **"No repro yet"** and lists the exact diagnostics to collect (error text verbatim, console/server log window with timestamp, HAR capture, screen recording) — never invented steps that "probably" trigger it.
+
+6. **Split expected vs actual into two concrete lines.** ✅ Expected: *"order total recalculates to pre-coupon price"* / Actual: *"total keeps the discount, button stays disabled"* — ❌ *"it doesn't work right"*. Attach the verbatim error message if one exists; paraphrased errors are unsearchable.
+
+7. **Call severity and priority separately** with one line of reasoning each, using the matrix in [`templates/bug-ticket.md`](templates/bug-ticket.md):
+   - **Severity** = worst plausible user impact: S1 data loss / security / payment broken · S2 core flow broken, no workaround · S3 degraded, workaround exists · S4 cosmetic
+   - **Priority** = business urgency: P1 drop everything · P2 this sprint · P3 backlog
+   A cosmetic bug on the pricing page during launch week is S4/P1 — the separation is the point. State the blast radius guess: who's affected (`all users` / `Safari only` / `one tenant`) and tag it.
+
+8. **Offer hypotheses as hypotheses.** Up to 3, each with a 5-minute check that would confirm or kill it. ✅ *"H1: expired-coupon validation leaves cart state locked — check: apply/remove a valid coupon, see if button recovers"*. Never present the leading hypothesis as the cause; that anchors the investigation on a guess.
+
+9. **Finish with duplicate-search hints** — 2–3 search strings for the tracker (error code, symptom phrasing, component name) so the ticket isn't the third copy.
+
+## Useful references in this skill
+
+- [`templates/bug-ticket.md`](templates/bug-ticket.md) — the ticket skeleton with the severity/priority matrix and the no-repro diagnostics list
+
+## Quality bar
+
+- **An engineer can start without contacting the reporter.** Either the repro stands alone or the no-repro diagnostics list says exactly what to collect.
+- **Title findable by symptom search.** If the words a future reporter would type don't appear in it, retitle.
+- **Zero untagged claims.** Every factual statement is `[reported]`, `[verified]`, or `[assumption]` — a triager's authority comes from the tags.
+- **Severity and priority each have a stated reason**, and they were judged independently — one line each, no shared justification.
+- **Hypotheses ≤ 3, each with a concrete check.** A hypothesis without a check is a vibe.
+- **The verbatim error text is present** when any error was shown — quoted exactly, not paraphrased.
+
+## When to use this skill
+
+- ✅ A Slack/support complaint needs to become a ticket an engineer can pick up
+- ✅ "Can you write this up properly?" for a vaguely described bug
+- ✅ Triaging an inbound bug queue into severity/priority order
+- ✅ A flaky, "sometimes" bug that needs a diagnostics plan instead of guesswork
+
+## When NOT to use this skill
+
+- ❌ Actually fixing the bug — hand the ticket to `feature-implement-loop` or a human
+- ❌ A production incident in progress — mitigate first; this is queue work, not response work
+- ❌ The post-incident analysis — that's `postmortem-generator`
+- ❌ A feature request wearing a bug costume ("bug: there's no dark mode") — route to `user-story-splitter`
+
+## Anti-patterns to avoid
+
+- ❌ **Root-cause cosplay.** "It's probably the cache" stated as fact in the ticket body — now the investigation starts at the guess instead of the evidence.
+- ❌ **Repro steps that skip state.** "1. Go to checkout 2. See bug" — which account, which cart, which browser? Steps that don't start clean don't reproduce.
+- ❌ **Severity inflated to get attention** (everything S1) or priority used as severity (P1 because a VP reported it — that's priority, write it as priority).
+- ❌ **The interrogation.** Ten questions back to the reporter before writing anything; three ranked ones, then proceed with tags.
+- ❌ **Paraphrased error messages.** "Some kind of permissions error" when the dialog said `ERR_TENANT_SCOPE_403` — the exact string is the most diagnostic fact available.
+- ❌ **The kitchen-sink ticket.** Three symptoms, two feature requests, and a screenshot dump under one title. Split it.

package/skills/bug-triage/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "bug-triage",
+  "version": "0.1.0",
+  "description": "Turn a vague bug report (Slack message, support ticket, \"it's broken on mobile sometimes\") into an actionable ticket — searchable symptom title, numbered repro steps from a clean state, expected vs actual, severity separated from priority, evidence tagged reported-vs-verified, and labeled hypotheses instead of root-cause guesses. Use when the user wants to triage a bug, write up a bug report, turn a complaint into a ticket, or make a flaky issue actionable.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["feature-implement-loop", "postmortem-generator", "user-story-splitter"],
+  "tags": ["bug-triage", "bug-report", "ticket", "qa", "repro", "severity"],
+  "model": { "tier": "standard", "rationale": "Extraction plus judgment calls (severity vs priority, hypothesis ranking) — same shape as brief-intake: above light, below heavy." }
+}

package/skills/bug-triage/templates/bug-ticket.md

@@ -0,0 +1,86 @@
+# Bug-ticket template
+
+Every claim carries a tag: `[reported]` (the reporter says so), `[verified]` (confirmed by log/screenshot/own repro), `[assumption]` (triager's default). Untagged statements are the anti-pattern.
+
+```markdown
+# {Symptom + condition — searchable: "Checkout button stays disabled after removing expired coupon (Safari 17, guest cart)"}
+
+**Severity:** S{1–4} — {one line: worst plausible user impact}
+**Priority:** P{1–3} — {one line: business urgency, judged separately}
+**Blast radius:** {all users | segment | one tenant} `[reported|verified|assumption]`
+**Component (best guess):** {area} `[assumption]`
+
+## Summary
+
+{2–3 sentences: who hits it, doing what, with what result. No cause claims.}
+
+## Environment
+
+| Field | Value | Tag |
+|---|---|---|
+| App version / commit | … | `[verified]` |
+| OS / browser / device | … | `[reported]` |
+| Account / tenant type | … | `[reported]` |
+| First seen / last worked | … | `[reported]` |
+
+## Reproduction
+
+{Pick exactly one of the two blocks:}
+
+**Steps (from clean state):**
+1. {fresh session, named test account, starting URL}
+2. {observable action}
+3. {observable action → failure}
+**Reproduces:** {n/n attempts} `[verified]`
+
+**— or — No repro yet.** Collect:
+- Verbatim error text / screenshot of the exact moment
+- Console or server logs for {window} around {timestamp}
+- HAR capture / request ID of the failing call
+- Screen recording if UI-state dependent
+
+## Expected vs actual
+
+**Expected:** {concrete, one line}
+**Actual:** {concrete, one line}
+**Error (verbatim):** `{exact string, or "none shown"}`
+
+## Hypotheses (≤3 — each with a 5-minute check; none of these is a conclusion)
+
+| # | Hypothesis | Quick check |
+|---|---|---|
+| H1 | … | … |
+
+## Questions for reporter (≤3, ranked by diagnostic value)
+
+1. …
+
+## Duplicate-search hints
+
+`{error code}` · `{symptom phrase}` · `{component + verb}`
+
+## Split out (if the report contained more than one issue)
+
+- {symptom} → {new ticket ref / to be filed}
+```
+
+## Severity / priority matrix
+
+**Severity — worst plausible user impact (not who reported it):**
+
+| | Definition | Examples |
+|---|---|---|
+| S1 | Data loss, security exposure, payments broken | double-charge; cross-tenant read; corrupted saves |
+| S2 | Core flow broken, no workaround | can't log in; checkout dead-ends |
+| S3 | Degraded, workaround exists | export fails but copy-paste works; retry succeeds |
+| S4 | Cosmetic / minor friction | misalignment; typo; flicker |
+
+**Priority — business urgency (judged independently):**
+
+| | Definition |
+|---|---|
+| P1 | Drop current work; fix and ship now |
+| P2 | This sprint |
+| P3 | Backlog, batch with related work |
+
+Legitimate mismatches prove the separation: S4/P1 (typo in the price during launch week), S2/P3 (core flow of a feature being sunset next month).

package/skills/business-case/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: business-case
+description: Build a business case for a build/buy/defer investment decision — do-nothing always included as the baseline, benefits quantified as re-runnable calculations with confidence tags, full costs (build + run + opportunity), ranges instead of false precision, and the flip-assumption named. Use when the user needs to justify an investment, write a business case, compare build vs buy vs defer, or get budget/sponsor approval for an initiative.
+---
+
+# business-case
+
+Produces the document a sponsor can approve, challenge, or kill on its merits — because every benefit shows its arithmetic, every option includes the one nobody advocates for (doing nothing), and the case names the single assumption that flips the recommendation. Decides *whether to invest*; `tech-comparison-matrix` picks between technologies after, `prd-draft` captures requirements after, `exec-summary` compresses this doc for a board.
+
+## How to respond
+
+1. **Pin the decision and the decider.** What exactly is being decided ("invest ~3 engineer-quarters in X" — not "improve our tooling"), who decides, and by when. Ask at most 2 questions, spent on the **cost of the status quo** ("what does the current state cost per month, in what units?") and the **decision deadline**. A business case without a named decision is an essay.
+
+2. **Always include Option 0: do nothing.** Costed like every other option — the status quo has a price (ongoing pain, growing risk, deferred opportunity) and the case must beat it *explicitly*, not by assumption. Then 2–3 real alternatives (typically build / buy / partial-defer). Every option presented is one someone could genuinely champion; a lineup of two strawmen escorting the preferred option is theater, and reviewers smell it.
+
+3. **Quantify benefits as calculations a reviewer can re-run.** Every benefit shows: the formula, each input with its source tag, and a **confidence tag** (high = measured data, medium = reasonable extrapolation, low = informed guess). ✅ *"40 agents × ~20 min/ticket saved `[data: time study]` × 30 tickets/day → 18–24 FTE-hours/day, confidence: medium (assumes 75–100% of tickets touch the flow)"* — ❌ *"significant efficiency gains"* — an adjective benefit is a benefit that didn't survive arithmetic.
+
+4. **Use ranges, never false precision.** Three estimates multiplied together do not produce "327% ROI" — they produce a range, and the case says which end is likelier and why. State payback as a range too ("breakeven month 7–11"). Single-point outputs from multi-guess inputs are the most reliable sign a case is selling, not informing.
+
+5. **Cost all three layers, per option**: **build** (people × time, the dominant and most-lowballed term — include ramp-up and the integration tail), **run** (infra, licenses, support burden, maintenance — the layer "buy" options hide in year 2+ pricing and "build" options hide in maintenance), and **opportunity** (what these people would otherwise ship — name the displaced thing, don't leave it abstract).
+
+6. **Name the flip-assumption.** The sensitivity question, answered honestly: *which single input, if wrong, reverses the recommendation?* ✅ *"The case rests on ≥60% agent adoption; below ~40%, Option 0 wins — adoption is `[low confidence]`, so we propose a 4-week pilot before full commit."* If no single assumption flips it, say which *pair* does. A case with no flip-condition is claiming certainty it cannot have.
+
+7. **Recommend one option, committally.** The recommendation names the option, the reasoning in two sentences, what was given up (the strongest point of the runner-up, stated fairly), and any de-risking step (pilot, staged commit) tied to the flip-assumption. "It depends" is the analyst's job half-done; the decider can disagree with a recommendation, but they can't disagree with a shrug.
+
+8. **Lead with the ask.** The first lines of the document: the decision requested, the cost, the headline benefit range, the deadline. ✅ *"Ask: approve 3 engineer-quarters (~$210k loaded) for Option B; expected payback month 7–11; decision needed by July 1 to hit Q4 capacity."* Emit with [`templates/business-case.md`](templates/business-case.md), one message.
+
+## Useful references in this skill
+
+- [`templates/business-case.md`](templates/business-case.md) — the skeleton: ask-first structure, option table, benefit-calculation blocks, sensitivity section
+
+## Quality bar
+
+- **Option 0 is present and costed.** A case that doesn't price the status quo hasn't established there's a problem worth money.
+- **Every benefit is a re-runnable calculation** with sourced inputs and a confidence tag. Reviewers check arithmetic; they can't check adjectives.
+- **Outputs are ranges; the case says which end is likelier.** False precision fails the doc even when the direction is right.
+- **All three cost layers appear per option** — build, run, opportunity — with the displaced work named, not waved at.
+- **The flip-assumption is identified** and, where confidence on it is low, a de-risking step is proposed before full commitment.
+- **The recommendation is singular and the runner-up's best argument is stated fairly.** A case that strawmans the alternative converts no skeptics.
+- **The ask is the first thing read** — option, cost, benefit range, deadline, in under 40 words.
+
+## When to use this skill
+
+- ✅ "Should we build this?" / "write the business case for X"
+- ✅ Build vs buy vs defer with real money or quarters at stake
+- ✅ Budget/headcount approval needs a document, not a hallway pitch
+- ✅ A persistent "we should really fix this" needs its cost of inaction priced
+
+## When NOT to use this skill
+
+- ❌ The investment decision is already made — go to `prd-draft`
+- ❌ Choosing between technologies for an approved initiative — `tech-comparison-matrix`
+- ❌ Compressing an existing case for execs — `exec-summary`
+- ❌ Trivial cost ("should we buy a $400/yr tool") — the case costs more than the decision; just decide
+
+## Anti-patterns to avoid
+
+- ❌ **Omitting do-nothing.** Every option looks good against an unexamined status quo — that's why it gets omitted.
+- ❌ **Adjective benefits.** "Improved efficiency, better experience, reduced risk" — three claims, zero numbers, nothing a reviewer can challenge.
+- ❌ **False precision.** "327% ROI" from three guesses. Ranges with a stated lean, always.
+- ❌ **Year-one costing.** Build cost without run cost — the buy option's renewal pricing and the build option's maintenance both live in year 2+, which is where cases go to die.
+- ❌ **Sunk-cost scaffolding.** "We've already invested 2 quarters" argues for nothing; the case is forward-looking from today's zero.
+- ❌ **Option theater.** Two deliberately weak alternatives flanking the favorite. Reviewers notice, and the case loses its credibility along with the vote.
+- ❌ **Burying the ask.** Page 4, paragraph 2, "in light of the above we suggest…" — the sponsor read the first five lines; the ask lives there or nowhere.

package/skills/business-case/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "business-case",
+  "version": "0.1.0",
+  "description": "Build a business case for a build/buy/defer investment decision — do-nothing always included as the baseline, benefits quantified as re-runnable calculations with confidence tags, full costs (build + run + opportunity), ranges instead of false precision, and the flip-assumption named. Use when the user needs to justify an investment, write a business case, compare build vs buy vs defer, or get budget/sponsor approval for an initiative.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["exec-summary", "prd-draft", "tech-comparison-matrix"],
+  "tags": ["business-case", "investment", "build-vs-buy", "roi", "cost-benefit", "decision"],
+  "model": { "tier": "heavy", "rationale": "Weighted multi-option judgment with a committal recommendation — same failure mode as tech-comparison-matrix: cheaper models mis-weight costs, inflate benefits, and miss the flip-assumption. Never downgrade." }
+}

package/skills/business-case/templates/business-case.md

@@ -0,0 +1,60 @@
+# Business-case template
+
+Ask first. Ranges, not points. Every number traceable to a tagged input.
+
+```markdown
+# Business case: {decision, named — "Invest 3 engineer-quarters in unified agent view"}
+
+## The ask (≤40 words)
+
+Approve **{option}** — {cost range, loaded} — expected {headline benefit range},
+payback {range}. Decision needed by **{date}** because {what the deadline forfeits}.
+
+**Decider:** {role} · **Author:** {role} · **Date:** {YYYY-MM-DD}
+
+## The problem, priced
+
+{2–3 sentences: what the status quo costs per month, in units the decider budgets
+in (FTE-hours, churn, incidents, $). Inputs tagged [data:…] / [reported:…] / [estimate].}
+
+## Options
+
+| | Option 0: do nothing | Option A: {…} | Option B: {…} |
+|---|---|---|---|
+| Build cost | — | {range, loaded, incl. ramp + integration tail} | {range} |
+| Run cost (annual, yr 2+) | {status-quo ongoing cost} | {infra + licenses + maintenance} | {…} |
+| Opportunity cost | {what worsens by deferring} | {the displaced work, named} | {…} |
+| Headline benefit | 0 (baseline) | {range + confidence} | {range + confidence} |
+| Time to value | — | {range} | {range} |
+| Champion-able? | yes — {who'd argue it} | yes — {…} | yes — {…} |
+
+## Benefit calculations (re-runnable)
+
+### {Benefit 1, Option A}
+- Formula: {inputs → output}
+- Inputs: {value [data: source]} × {value [estimate]} × …
+- Result: **{range}** · Confidence: {high|medium|low} — {why}
+
+{Repeat per material benefit. A benefit with no calculation block doesn't appear in the option table.}
+
+## Sensitivity — the flip-assumption
+
+**The recommendation flips if:** {single input + the threshold — "agent adoption < ~40%"}
+**Confidence on that input:** {tag} → **De-risking step:** {pilot / staged commit / data pull, with cost and duration}
+{If no single input flips it, name the pair that does.}
+
+## Recommendation (one option)
+
+**{Option}.** {Two sentences of reasoning.}
+**What we give up:** {the runner-up's strongest point, stated fairly.}
+**Conditions:** {the de-risking step above; any staging of the commitment.}
+
+## Risks beyond the numbers
+
+- {execution/organizational/vendor risk} — {mitigation or acceptance, one line each}
+
+## Not in this case
+
+{What was deliberately excluded from the math (unquantifiable strategic upside,
+morale, …) — named so the decider can weigh it qualitatively, not smuggled into the numbers.}
+```

package/skills/capacity-cost-model/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: capacity-cost-model
+description: Build a capacity and cost model for a service or feature — sized from a demand driver and its growth curve, not from instance types; unit economics (cost per request/tenant/GB); peak-vs-average and headroom as explicit decisions; cost at 1×/3×/10× with scaling cliffs named; and the forgotten line items (egress, logging, NAT, non-prod) checklisted. Use when the user needs to estimate cloud/infra cost, size capacity for launch or growth, project the bill at scale, or find what's driving a cost.
+---
+
+# capacity-cost-model
+
+Turns "how much will this cost to run?" into a model a reviewer can re-run and finance can trust — sized from **demand**, expressed in **cost per unit**, and honest about the line items everyone forgets until the invoice. Distinct from `business-case` (which decides *whether* to invest, across options) and `nfr-spec` (which *sets* the throughput/availability targets); this models the resources and dollars to *meet* a target you've already chosen.
+
+## How to respond
+
+1. **Start from the demand model, never from instance types.** The first question is "how much of what?" — the **driver** (requests/sec, tenants, GB stored, events/day, concurrent users), its **current value**, its **growth curve**, and the **peak-to-average ratio**. Ask at most 2 questions, spent on the driver's current volume + source and the peak ratio (the spikiness that decides static-vs-autoscale). Sizing to a round instance count instead of to demand is how clusters end up 80% idle or 200% over.
+
+2. **Express everything as unit economics.** Cost per request / per tenant / per 1k events / per GB-month — because that's what scales predictably, what finance budgets in, and what reveals whether the architecture gets cheaper or more expensive per unit as it grows. ✅ *"$0.012 per active tenant per day, dominated by the per-tenant search index"* — ❌ *"about $4k/month"* (a number with no denominator can't be reasoned about at 10×).
+
+3. **Model the components against the cost catalog** ([`reference.md`](reference.md)) — compute, storage, **network egress** (the forgotten heavyweight), managed-service tiers, **logging/observability** (routinely a top-3 surprise), backups/DR, data transfer cross-AZ/region, and **non-production environments** (dev/staging/idle often 30–50% of the bill). Each line: the quantity from the demand model × the unit price, with the price's source/date tagged. Missing the egress and observability lines is the single most common way a model lands 40% low.
+
+4. **Make peak-vs-average and headroom explicit decisions, not defaults.** State both the average load (what you bill for) and the peak (what you must serve), and the chosen **target utilization + buffer** with its reasoning: ✅ *"size to peak × 1.3 for failover + spike; accept ~55% average utilization because the spike is revenue-critical"*. Over-provisioning burns money; under-provisioning is an incident — the headroom number is where that tradeoff is decided, so it's named, not buried in a rounded-up instance count.
+
+5. **Project at 1× / 3× / 10× and find the scaling cliffs.** Cost rarely scales linearly — name where it jumps: the next instance/managed-service tier, cross-AZ egress kicking in, a license seat band, single-node → sharded, a free-tier ceiling. ✅ *"linear to ~5×, then the search tier forces a sharded cluster (+$3k/mo step) at ~6×"*. A model that's a single multiplication hides the cliff that wrecks the budget.
+
+6. **Rank the cost drivers and use ranges.** The 2–3 line items that dominate get named (optimization targets them, not the rounding error). Outputs are **ranges with a stated lean** (low/expected/high), never false precision — three estimated inputs don't produce "$4,271/mo". Tag input confidence like `business-case` does.
+
+7. **Set the cost guardrails.** Budget alert thresholds, and the **unit-cost regression check**: cost-per-unit should hold flat or fall as volume grows; if the model shows it *rising* with scale, that's a flagged architectural problem, not a footnote. (Mirrors `success-metrics`' guardrail discipline; the alerting itself is an `nfr-spec` cost target.)
+
+8. **Emit with [`templates/cost-model.md`](templates/cost-model.md)** in one message: demand model, component table with unit prices, unit economics, total at average + peak, growth scenarios with cliffs, cost-driver ranking, the forgotten-costs checklist (each ticked present or n/a), and guardrails. State the assumptions that most move the total at the top.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the cost-component catalog, the forgotten-costs checklist, headroom guidance, and common scaling cliffs
+- [`templates/cost-model.md`](templates/cost-model.md) — the model skeleton with demand, component, and growth-scenario tables
+
+## Quality bar
+
+- **Sized from a demand driver with a growth curve**, not a chosen instance count. The driver and its source are stated.
+- **Every cost is a unit cost × a quantity**, with the unit price's source and date tagged. A bare monthly total fails.
+- **Egress, observability, and non-prod lines are present** (or explicitly n/a). Their absence is the signature of a model that's 40% low.
+- **Headroom and peak-vs-average are explicit decisions** with reasoning, not absorbed into a rounded number.
+- **Scaling cliffs are named in the 1×/3×/10× projection.** A linear extrapolation that hides a tier jump is a budget trap.
+- **Outputs are ranges with a lean; the unit-cost-at-scale trend is checked.** Rising per-unit cost with growth is flagged as an architecture issue.
+
+## When to use this skill
+
+- ✅ Estimating run cost for a new service/feature before launch
+- ✅ Sizing capacity for a launch or a known growth event
+- ✅ "What will this cost at 10× / when we hit N tenants?"
+- ✅ Finding what's driving an existing cloud bill and where the next cliff is
+
+## When NOT to use this skill
+
+- ❌ Deciding whether to build/buy/invest at all — that's `business-case` (this can feed its run-cost line)
+- ❌ Setting the performance/availability targets — that's `nfr-spec` (this sizes to meet them)
+- ❌ The migration/rollout sequence — that's `migration-plan`
+- ❌ A fixed-price SaaS seat with no scaling math — just read the price sheet
+
+## Anti-patterns to avoid
+
+- ❌ **Sizing from instance types.** "Let's run 3 large nodes" before knowing the load — that's a guess wearing a SKU, idle or overwhelmed by luck.
+- ❌ **The denominator-free total.** "$4k/month" with no per-unit cost can't be projected, compared, or optimized.
+- ❌ **Forgetting egress and observability.** The two line items that turn a tidy estimate into a 40%-low one; the checklist exists because they're forgotten every time.
+- ❌ **Ignoring non-prod.** Three idle staging environments and a never-scaled-down dev cluster are real money the model pretends doesn't exist.
+- ❌ **Linear extrapolation past a cliff.** "10× the load, 10× the cost" right up until the sharded-cluster step doubles it. Name the cliff.
+- ❌ **False precision.** "$4,271.40/mo" from estimated inputs reads as certainty the model doesn't have. Ranges with a lean.
+- ❌ **Missing the rising-unit-cost flag.** A model where cost-per-tenant climbs with scale is describing an architecture that gets worse the more it succeeds — that's the headline, not a row.

package/skills/capacity-cost-model/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "capacity-cost-model",
+  "version": "0.1.0",
+  "description": "Build a capacity and cost model for a service or feature — sized from a demand driver and its growth curve, not from instance types; unit economics (cost per request/tenant/GB); peak-vs-average and headroom as explicit decisions; cost at 1×/3×/10× with scaling cliffs named; and the forgotten line items (egress, logging, NAT, non-prod) checklisted. Use when the user needs to estimate cloud/infra cost, size capacity for launch or growth, project the bill at scale, or find what's driving a cost.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["business-case", "migration-plan", "nfr-spec", "success-metrics"],
+  "tags": ["capacity-planning", "cost", "cloud", "finops", "sizing", "unit-economics"],
+  "model": { "tier": "standard", "rationale": "Quantitative projection from a demand model against a fixed cost catalog. Headroom and scaling-cliff judgment is bounded by the reference; escalate via ambiguous-input on novel architectures." }
+}

package/skills/capacity-cost-model/reference.md

@@ -0,0 +1,54 @@
+# capacity-cost-model reference — component catalog, forgotten costs, cliffs
+
+All unit prices are illustrative placeholders — the skill tags each with its real source and date. Cloud pricing changes; never hard-code a number without a date.
+
+## Cost-component catalog (model every applicable line)
+
+| Component | Demand quantity | Typical unit price shape | Notes |
+|---|---|---|---|
+| **Compute** | peak concurrent work / rps | $/vCPU-hr, $/instance-hr, $/request (serverless) | size to peak or autoscale; state which |
+| **Storage** | GB stored × growth | $/GB-month, tiered (hot/warm/cold) | growth is cumulative — model the curve, not a point |
+| **Network egress** | GB out to internet / cross-region | $/GB, often tiered, free inbound | THE forgotten heavyweight; cross-AZ counts too |
+| **Managed services** (DB, cache, queue, search) | IOPS, nodes, throughput units | per-node / per-RU / per-throughput-tier | tier jumps are the classic cliff |
+| **Logging / observability** | GB ingested, metrics cardinality, traces | $/GB ingested, $/metric series | routinely top-3; high-cardinality labels explode it |
+| **Backups / DR** | snapshot GB, replica count, cross-region copy | $/GB-month × retention × copies | retention × copies multiplies fast |
+| **Data transfer** | inter-service, cross-AZ, cross-region | $/GB | "internal" traffic is not always free |
+| **Non-production** | dev + staging + preview envs | fraction of prod, often 30–50% | idle/never-scaled-down is pure waste — model it |
+| **Support / licenses** | seats, support plan %, per-seat tools | $/seat, % of spend | seat bands are a cliff |
+| **Idle / always-on** | min instances, provisioned capacity, NAT gateways | $/hr regardless of load | NAT gateways and provisioned concurrency bill 24/7 |
+
+## Forgotten-costs checklist (tick each: present / n/a-with-reason)
+
+- [ ] Network egress to internet
+- [ ] Cross-AZ / cross-region data transfer
+- [ ] Logging & observability ingestion (and metric cardinality)
+- [ ] Backups × retention × replica copies
+- [ ] Non-prod environments (dev/staging/preview), incl. idle
+- [ ] NAT gateway / load balancer / always-on networking
+- [ ] Provisioned-but-idle capacity (min autoscale floor, reserved-but-unused)
+- [ ] Support plan (% of spend) and per-seat tooling
+- [ ] Data egress on delete/migration (one-time but real)
+- [ ] Free-tier expiry (the bill that appears in month 13)
+
+A model that hasn't consciously cleared this list is presumed 30–40% low.
+
+## Headroom guidance (state the decision)
+
+- **Target utilization:** the average you design for. 50–70% is common for spiky interactive workloads; 80%+ only for smooth, predictable, non-critical load.
+- **Buffer:** peak × (failover redundancy + spike margin). N+1 across AZs is a multiplier, not a rounding.
+- **Autoscale vs static:** if peak-to-average > ~2–3×, autoscaling usually beats provisioning for peak. State the floor (min capacity bills 24/7) and the scale-up latency (cold starts during a spike are an availability risk, an `nfr-spec` concern).
+- The headroom number is a money-vs-incident tradeoff — write the reasoning, not just the multiplier.
+
+## Common scaling cliffs (name the one that bites first)
+
+- **Managed-service tier jump** — DB/cache/search moves to the next node size or shard count; cost steps, not slopes.
+- **Single-node → distributed** — replication, coordination, and cross-node transfer appear all at once.
+- **Cross-AZ egress threshold** — multi-AZ for HA turns "internal" traffic into a metered line.
+- **Free-tier / committed-use ceiling** — the discount or free allowance runs out; effective unit price jumps.
+- **License/seat band** — per-seat tools and support plans step at user-count thresholds.
+- **Observability cardinality wall** — a new label dimension multiplies metric series and the bill with them.
+- **Connection/throughput limits** — hitting a managed service's connection cap forces a proxy/pooler tier.
+
+## Unit-cost-at-scale check
+
+Compute cost-per-unit at 1×, 3×, 10×. The healthy shape is flat or declining (economies of scale). If per-unit cost **rises** with volume, the model has found an architectural anti-pattern (per-tenant fixed overhead, N² chatter, cardinality explosion) — surface it as the headline finding, because it means success makes the economics worse.

package/skills/capacity-cost-model/templates/cost-model.md

@@ -0,0 +1,68 @@
+# Capacity & cost-model template
+
+Demand first, unit costs always, ranges not points, cliffs named. Every unit price tagged with source + date.
+
+```markdown
+# Capacity & cost model: {service / feature}
+
+**Date:** {YYYY-MM-DD} · **Cloud/region:** {provider, region}
+
+## Assumptions that most move the total (top 3)
+
+- {driver value, headroom choice, or unit price the answer is most sensitive to} `[data|estimate]`
+
+## Demand model
+
+| Driver | Current | Growth | Peak : average | Source |
+|---|---|---|---|---|
+| {requests/sec | tenants | GB | events/day} | {value} | {curve, e.g. 8%/mo} | {e.g. 4:1} | `[data: …]` |
+
+## Components (quantity × unit price)
+
+| Component | Quantity (from demand) | Unit price (source, date) | Monthly (expected) | Range |
+|---|---|---|---|---|
+| Compute | {peak/autoscale} | {$/…} `[src 2026-06]` | {$} | {low–high} |
+| Storage | {GB, cumulative} | {$/GB-mo} | {$} | |
+| Egress | {GB out} | {$/GB} | {$} | |
+| Managed: {db/cache/search} | {tier/nodes} | {$/node} | {$} | |
+| Observability | {GB ingest, series} | {$/GB} | {$} | |
+| Backups/DR | {GB × retention × copies} | {$/GB-mo} | {$} | |
+| Non-prod | {fraction of prod} | — | {$} | |
+| Always-on (NAT/LB/floor) | {24/7 units} | {$/hr} | {$} | |
+| **Total (average load)** | | | **{$ range}** | |
+| **Total (peak provisioned)** | | | **{$ range}** | |
+
+## Unit economics
+
+- Cost per {request | tenant | 1k events | GB}: **{$ expected (range)}**
+- Dominated by: {the line item driving it}
+
+## Growth scenarios & cliffs
+
+| Scale | Monthly cost (range) | Cost per unit | Cliff hit? |
+|---|---|---|---|
+| 1× (today) | {$} | {$/unit} | — |
+| 3× | {$} | {$/unit} | {none / names it} |
+| 10× | {$} | {$/unit} | **{e.g. search → sharded cluster, +$3k step at ~6×}** |
+
+**Unit-cost trend:** {flat / declining / ⚠ rising — and why if rising}
+
+## Cost-driver ranking (optimize these, not the rounding error)
+
+1. {line item} — {% of total} — {lever to reduce}
+2. …
+
+## Forgotten-costs checklist
+
+{egress · cross-AZ · observability · backups×retention×copies · non-prod · NAT/LB ·
+idle floor · support/licenses · migration egress · free-tier expiry — each: ✅ included / n/a (reason)}
+
+## Headroom decision
+
+Target utilization {x%}; buffer = peak × {multiplier} for {failover + spike}; {autoscale | static} because {peak:avg ratio}. Tradeoff accepted: {money vs incident}.
+
+## Guardrails
+
+- Budget alert at {threshold}; hard stop / review at {threshold}.
+- Unit-cost regression: alert if cost-per-{unit} rises > {x%} quarter-over-quarter.
+```