skilldrop-cli 0.2.0

package/skills/nfr-spec/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: nfr-spec
+description: Sweep a feature or system through the full non-functional requirements catalog — performance, throughput, availability, durability, privacy/retention, accessibility, i18n, observability, operability, compatibility, cost — forcing every category to a measurable target, an explicit n/a, or a tagged default. Use when the user needs NFRs, quality attributes, "how fast/reliable does it need to be", SLO targets for a feature, or the requirements everyone forgets until they're incidents.
+---
+
+# nfr-spec
+
+Gathers the requirements nobody volunteers: the business says what the feature does, this skill pins down **how well** — with numbers. Every category in the catalog ends in exactly one of three states: a **measurable target with a verification method**, an explicit **n/a with a reason**, or an **accepted default tagged `[assumption]`**. Silence is the one forbidden state. Downstream of `prd-draft`; feeds `design-doc` (targets shape the architecture), `test-plan-generator` (verification methods become test cases), and `threat-model` (security depth lives there, not here).
+
+## How to respond
+
+1. **Classify the system first** — the archetype sets the defaults: customer-facing SaaS, internal tool, public API, batch/pipeline, mobile/edge. Ask at most 2 questions, spent on the two answers that move the most targets: **user-facing or internal**, and **what happens when it's down for an hour** (the honest availability requirement hides in that answer). Everything else: archetype default + `[assumption]`.
+
+2. **Sweep every category in [`reference.md`](reference.md)** — performance/latency, throughput/capacity, availability/SLO, durability/backup/DR, privacy/retention/residency, accessibility, i18n/l10n, observability, operability, compatibility, cost. For each: target, verification, or n/a-with-reason. The output includes the **full ledger** so a reviewer sees the sweep happened — a skipped category is indistinguishable from a forgotten one otherwise.
+
+3. **Force numbers tied to business reality, not aspiration.** ✅ *"p95 search < 800ms at 2× current peak (peak = 120 rps `[data: April dashboard]`)"* — ❌ *"sub-second response times"* (which percentile? at what load?) — ❌ *"99.999% availability"* for an internal tool whose users sleep at night (five nines costs 100× three nines; the archetype default exists to stop this).
+
+4. **Attach a verification method to every target** — the method that would prove it before launch, not after: load test at stated volume, chaos drill, restore-from-backup rehearsal, axe-core scan + screen-reader pass, locale pseudo-translation run, cost projection at target volume. An NFR without a verification is a hope with units. These methods hand straight to `test-plan-generator`.
+
+5. **Make retention and deletion first-class.** For every data class the feature touches: what's stored, how long, where (residency), and **how deletion actually happens** (user-triggered, TTL, legal hold override). "We keep it forever" is a decision with legal weight — make it visible, never implicit.
+
+6. **State observability as requirements, not tooling.** What must be answerable at 3am: ✅ *"On-call can see per-tenant error rate and the last deploy time within 2 minutes of an alert"* — ❌ *"Use Datadog"*. The instrument choice is `design-doc`'s; the questions-it-must-answer are NFRs.
+
+7. **Point, don't duplicate, for security.** One line stating the auth/data-classification posture, then hand depth to `threat-model`. An NFR doc with a 3-page security section has stolen another skill's job and done it worse.
+
+8. **Emit with [`templates/nfr-spec.md`](templates/nfr-spec.md)**: summary table (category / target / verification / state), per-category detail, the n/a ledger, assumptions log, and the handoff map.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the category catalog with per-archetype defaults and the verification menu
+- [`templates/nfr-spec.md`](templates/nfr-spec.md) — the ledger-style output skeleton
+
+## Quality bar
+
+- **Every category lands in one of three states** — target, n/a-with-reason, or tagged default. The ledger shows all of them; silence fails the doc.
+- **Every target has a percentile, a load condition, and a verification.** A latency number without load is a screenshot of a quiet day.
+- **Availability matches the down-for-an-hour answer**, not the marketing instinct. The cost of each extra nine is named when the target exceeds the archetype default.
+- **Every data class has a retention period and a deletion mechanism.** "Indefinite" is written as the decision it is.
+- **Accessibility names level and scope** — "WCAG 2.2 AA on all agent-facing screens, axe + manual screen-reader pass" — not "accessible".
+- **Cost has a number at target volume**, or a tagged `[assumption]` placeholder that explicitly hands the sizing to `capacity-cost-model`. Either way the line is present — an NFR spec that's silent on cost has delegated it to the first invoice.
+
+## When to use this skill
+
+- ✅ A PRD is done and the quality targets need pinning before design
+- ✅ "How fast / how reliable / how much does this need to be?"
+- ✅ Defining SLOs for a new service or feature
+- ✅ A legacy system getting its implicit NFRs written down for the first time
+
+## When NOT to use this skill
+
+- ❌ Functional requirements — that's `prd-draft`
+- ❌ Security threat depth — one posture line here, the analysis is `threat-model`
+- ❌ Designing the architecture that meets the targets — `design-doc`
+- ❌ Writing the verification tests themselves — hand the methods to `test-plan-generator`
+
+## Anti-patterns to avoid
+
+- ❌ **"As fast as possible."** That's a budget of infinity. Every performance target gets a percentile, a number, and a load.
+- ❌ **Five-nines cargo cult.** Availability copied from a FAANG blog onto an internal CRUD tool — each nine multiplies cost; the down-for-an-hour question calibrates honestly.
+- ❌ **Uniform targets.** The same p95 for search, checkout, and a monthly export means nobody thought about any of them.
+- ❌ **"GDPR compliant" as the entire privacy section.** Which data, retained how long, deleted how, stored where — compliance is the output of those answers, not a substitute for them.
+- ❌ **Tool names as observability requirements.** "Use Prometheus" survives a migration to nothing; "alert fires within 2 min of error-rate breach" survives any tool.
+- ❌ **Untestable NFRs.** "The system shall be maintainable" — if no verification method exists, it's culture, not a requirement; cut it or make it measurable.

package/skills/nfr-spec/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "nfr-spec",
+  "version": "0.1.0",
+  "description": "Sweep a feature or system through the full non-functional requirements catalog — performance, throughput, availability, durability, privacy/retention, accessibility, i18n, observability, operability, compatibility, cost — forcing every category to a measurable target, an explicit n/a, or a tagged default. Use when the user needs NFRs, quality attributes, \"how fast/reliable does it need to be\", SLO targets for a feature, or the requirements everyone forgets until they're incidents.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["capacity-cost-model", "design-doc", "prd-draft", "test-plan-generator", "threat-model"],
+  "tags": ["nfr", "requirements", "slo", "performance", "availability", "quality-attributes"],
+  "model": { "tier": "standard", "rationale": "Rubric-driven sweep with archetype defaults; the judgment is calibrating targets to business reality. Bounded by the catalog; escalate via ambiguous-input on contested SLOs." }
+}

package/skills/nfr-spec/reference.md

@@ -0,0 +1,74 @@
+# nfr-spec reference — category catalog, archetype defaults, verification menu
+
+Defaults are starting points, always tagged `[assumption]` in the output. The archetype row is chosen once in step 1 and reused everywhere.
+
+## Archetypes
+
+| Archetype | Examples | Posture |
+|---|---|---|
+| customer-facing SaaS | checkout, dashboards | user-perceived latency and availability dominate |
+| internal tool | admin panels, back-office | availability honesty — business hours usually suffice |
+| public API | partner integrations | contract stability, rate limits, versioning weight |
+| batch / pipeline | ETL, reports, billing runs | completion deadlines and replayability, not latency |
+| mobile / edge | apps, POS | offline behavior, payload size, OS-version spread |
+
+## Category catalog (sweep all 11 — every one lands in target / n/a+reason / default+tag)
+
+### 1. Performance / latency
+Target shape: `p50/p95 < N ms for {operation} at {load}`. Per key operation, not uniform.
+Defaults: SaaS interactive p95 < 500ms; internal tool p95 < 2s; API p95 < 300ms; batch n/a → see deadline; mobile interaction < 100ms perceived.
+
+### 2. Throughput / capacity
+Target shape: `sustains N rps / M jobs/hr at target latency; designed headroom ×K`.
+Defaults: 2× current peak headroom; batch: completes within window at 3× current data volume.
+
+### 3. Availability / SLO
+Target shape: `N% monthly, measured at {user-visible boundary}; error budget stated`.
+Defaults: SaaS 99.9%; internal tool 99.5% business-hours; public API 99.95%; batch: deadline-based ("billing run completes by 06:00, 99% of months").
+Calibrate with the down-for-an-hour answer; name the cost when exceeding the default — each nine roughly 10×es the engineering.
+
+### 4. Durability / backup / DR
+Target shape: `RPO ≤ N min, RTO ≤ M min; backup restore rehearsed {cadence}`.
+Defaults: transactional data RPO ≤ 5 min / RTO ≤ 1h; derived/rebuildable data RPO n/a with reason "recomputable from source in N h".
+
+### 5. Privacy / retention / residency
+Per data class: what's stored · classification (PII? payment? health?) · retention period · deletion mechanism (user-triggered / TTL / legal hold) · residency constraint.
+Default: no new PII without a named retention period; "indefinite" written explicitly as a decision.
+
+### 6. Accessibility
+Target shape: `WCAG {version} {level} on {scope}; verified by {automated + manual}`.
+Defaults: customer-facing WCAG 2.2 AA; internal tools AA for core flows `[assumption — confirm with HR/legal jurisdiction]`.
+
+### 7. Internationalization / localization
+Target shape: locales supported at launch; text expansion tolerance; date/number/currency handling; RTL yes/no.
+Default: single-locale launch is fine **if stated**; unicode-correct storage is non-negotiable either way.
+
+### 8. Observability
+Requirement shape: the 3am questions — `on-call can answer {question} within {time}` — plus alert conditions with thresholds and a paging severity. Tool names excluded.
+Default minimum: error rate, latency, and saturation per surface; alert before users notice (burn-rate, not static threshold, for SLO'd surfaces); every alert maps to a runbook entry (→ `runbook-generator`).
+
+### 9. Operability
+Deploy/rollback time targets, config-change blast radius, feature-flag kill switch, dependency-down behavior (degrade vs fail closed — chosen per dependency).
+Default: rollback ≤ 15 min; every new external dependency gets an explicit down-behavior.
+
+### 10. Compatibility
+Browsers/devices/OS floor; API consumer versions honored; data-format backward compatibility window.
+Default: SaaS = last 2 major browser versions; API = no breaking change without version bump (→ `api-contract-draft` policy).
+
+### 11. Cost
+Target shape: `≤ $N/month at target volume; alert at 80%`. Include the per-unit driver (per-tenant, per-GB, per-1k-requests).
+Default: projection required before launch; "we'll see" fails the ledger.
+
+## Verification menu (every target picks at least one)
+
+| Method | Proves |
+|---|---|
+| Load test at stated volume + headroom | latency, throughput |
+| Chaos / dependency-kill drill | availability, dependency-down behavior |
+| Backup-restore rehearsal (timed) | RPO/RTO are real, not configured |
+| Deletion end-to-end test (incl. backups/replicas) | retention/deletion actually deletes |
+| axe-core + manual screen-reader pass | accessibility level on scope |
+| Pseudo-locale build (text expansion, RTL) | i18n readiness |
+| Game-day: answer the 3am questions on a stage incident | observability requirements |
+| Timed rollback drill | operability targets |
+| Cost projection reviewed against first month's bill | cost model honesty |

package/skills/nfr-spec/templates/nfr-spec.md

@@ -0,0 +1,56 @@
+# NFR-spec template
+
+The ledger is the contract: all 11 categories appear, each in exactly one state — **target** / **n/a (reason)** / **default `[assumption]`**.
+
+```markdown
+# NFR spec: {feature / system}
+
+**Archetype:** {customer-facing SaaS | internal tool | public API | batch | mobile/edge}
+**Down-for-an-hour answer:** {verbatim from stakeholder — calibrates availability} `[reported]`
+**Date:** {YYYY-MM-DD} · **Feeds:** design-doc, test-plan-generator, threat-model
+
+## Ledger (all 11 — no silent rows)
+
+| # | Category | State | Target / reason | Verification |
+|---|---|---|---|---|
+| 1 | Performance | target | p95 < 800ms search @ 2× peak (120 rps) | load test |
+| 2 | Throughput | default `[assumption]` | 2× peak headroom | load test |
+| 3 | Availability | target | 99.9% monthly, user-visible boundary | chaos drill + SLO dashboard |
+| 4 | Durability/DR | target | RPO ≤ 5min, RTO ≤ 1h | timed restore rehearsal |
+| 5 | Privacy/retention | target | see data-class table | deletion end-to-end test |
+| 6 | Accessibility | target | WCAG 2.2 AA, all customer screens | axe + screen-reader pass |
+| 7 | i18n | n/a | single-locale launch, stated in PRD non-goals | — |
+| 8 | Observability | target | 3am questions below | game-day |
+| 9 | Operability | default `[assumption]` | rollback ≤ 15 min; per-dep down-behavior | rollback drill |
+| 10 | Compatibility | default `[assumption]` | last 2 major browsers | CI matrix |
+| 11 | Cost | target | ≤ $N/mo @ target volume, alert at 80% | projection vs first bill |
+
+## Per-category detail
+
+{One block per non-n/a row: the target restated with its load condition and
+source of the numbers, the verification method, and who owns it.}
+
+## Data classes (category 5 expanded)
+
+| Data | Classification | Retention | Deletion mechanism | Residency |
+|---|---|---|---|---|
+| {what} | {PII/payment/none} | {period or "indefinite — explicit decision"} | {TTL / user-triggered / legal-hold-aware} | {constraint or none} |
+
+## 3am questions (category 8 expanded)
+
+- On-call can answer "{question}" within {time}, from {alert/dashboard}.
+- Alert: {condition + threshold + paging severity} → runbook entry: {ref}.
+
+## Security posture (one line — depth lives in threat-model)
+
+{e.g. "Authn via platform SSO; tenant-scoped authz; PII per table above. Full analysis: threat-model."}
+
+## Assumptions log
+
+- [assumption] {default taken} — confirm with {role} by {date}
+
+## Exceeding-default justifications
+
+{Required whenever a target beats the archetype default: "99.95% chosen over 99.9%
+because {contractual SLA}; accepted cost: {on-call rotation, multi-AZ spend}."}
+```

package/skills/observability-plan/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: observability-plan
+description: Design an observability plan for a service — user-journey SLIs, SLOs with error budgets, symptom-based burn-rate alerting (page vs ticket, every page actionable and runbook-linked), and a deliberate metrics/logs/traces split with a cardinality and cost budget. Use when the user needs SLOs, alerting design, a monitoring/observability strategy, dashboards, or wants to fix alert fatigue and know what to measure.
+---
+
+# observability-plan
+
+Designs the telemetry that makes a service *debuggable at 3am and detectable before users complain* — SLOs measured from the user's experience, alerts that fire only when a human must act, and the three pillars each used for what they're good at. Expands the one-line observability requirement from `nfr-spec` into a full operating plan; upstream of `incident-comms` and `postmortem-generator` (you can't communicate or analyze an incident you couldn't detect). Distinct from `success-metrics` (business outcomes) — this is operational health.
+
+## How to respond
+
+1. **Start from user journeys, not from the resource dashboard.** The first artifact is the list of critical journeys ("log in", "place order", "load feed") — because an SLI measures *what the user experiences*, and CPU graphs measure what's easy. Ask at most 2 questions, spent on the most critical journey and what "down" means to a user there. Resource metrics (the golden signals) still get covered — but as saturation/cause signals, never as the SLO.
+
+2. **Define SLIs as good-events / valid-events from the user's side** (catalog in [`reference.md`](reference.md)) — availability (success rate), latency (a threshold, measured at a percentile: "% of requests < 300ms"), and where relevant freshness, correctness, throughput. ✅ *"SLI: proportion of checkout requests returning 2xx within 1s, measured at the load balancer"* — ❌ *"SLI: average CPU"* (the user never feels your CPU). Latency SLIs are a *threshold count*, not an average — averages hide the tail that hurts.
+
+3. **Set SLOs with an explicit error budget and window.** Each SLI gets a target over a rolling window: "99.9% over 28 days." That target *is* the error budget (0.1% = ~40 min/28d) — the quantity that governs both alerting and how aggressively you ship. State the budget in human terms (minutes/month) and name the **error-budget policy**: what happens when it's spent (freeze risky releases, redirect to reliability) — an SLO with no policy is a number nobody defends. Pick targets honestly (99.9% is not free; see `nfr-spec`'s down-for-an-hour calibration) — more nines is exponentially more cost.
+
+4. **Alert on symptoms, page only on what's actionable now.** The hard rule that kills alert fatigue: **a page means a human must act immediately; everything else is a ticket or a dashboard.** Alert on SLO burn (the user is being hurt), not on every cause (a single CPU spike that auto-recovered). Cause-based signals inform diagnosis once you're paged — they don't page. Use **multi-window, multi-burn-rate alerts** ([`reference.md`](reference.md)): a fast burn (budget being consumed quickly) pages; a slow burn opens a ticket. Every page is actionable, deduplicated, severity-tiered, and **maps to a runbook entry** (→ `runbook-generator`) — a page with no runbook is a 3am puzzle, not an alert.
+
+5. **Split the three pillars deliberately — each for what it's good at:**
+   - **Metrics** — cheap, aggregatable, the basis of SLOs and alerts. Low-cardinality. Answer "is it broken and how much?"
+   - **Logs** — expensive, high-detail, for debugging the specific failure. **Structured** (not string soup), sampled on the hot path, with a retention/cost budget. Answer "what exactly happened to this request?"
+   - **Traces** — request flow across services, for "where in the chain did the latency/error come from?" Sample intelligently (tail-based on errors/slow); propagate context across every hop.
+   Don't put in logs what should be a metric (cardinality and cost explode), and don't try to metric what needs a trace (you'll never reconstruct the path from counters).
+
+6. **Set a cardinality and cost budget.** High-cardinality labels (user_id, request_id, full URL) on metrics multiply time series and the bill without bound — name which labels are allowed on metrics (bounded sets: region, status_class, endpoint-template) and push the high-cardinality identifiers to logs/traces where they belong. State the log-volume and metric-series budget (ties to `capacity-cost-model`); observability is routinely a top-3 cloud line item.
+
+7. **Specify dashboards by the question each answers**, not by graph count. A service dashboard shows the golden signals + SLO/budget status at a glance (the at-a-glance health check); a debugging dashboard supports drill-down. The 3am questions from `nfr-spec` become concrete panels. A wall of 100 graphs is where signal goes to hide.
+
+8. **Emit with [`templates/observability-plan.md`](templates/observability-plan.md)** in one message: critical journeys, SLI/SLO table with error budgets, the error-budget policy, the alert table (condition / window / burn-rate / page-or-ticket / runbook link), the metrics-logs-traces split, the cardinality+cost budget, and dashboards-by-question. Instrumentation naming conventions and trace-context propagation noted.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — golden signals, SLI types by component, SLO/error-budget math, the multi-window burn-rate alert table, the metrics-vs-logs-vs-traces decision guide, and alert-quality rules
+- [`templates/observability-plan.md`](templates/observability-plan.md) — the plan skeleton with SLO, alert, and pillar tables
+
+## Quality bar
+
+- **SLIs measure user experience** (good/valid events), not resource utilization. Latency SLIs are threshold counts at a percentile, never averages.
+- **Every SLO has an error budget in human terms and a policy** for when it's spent. A target with no budget consequence is decoration.
+- **Pages are actionable, symptom-based, and runbook-linked.** If a page doesn't require an immediate human action, it's a ticket — the plan re-tiers it.
+- **Burn-rate alerting is used**, not static "CPU > 80%" thresholds, for SLO-backed surfaces.
+- **The three pillars are split by purpose**, with high-cardinality identifiers kept off metrics. Logs are structured and budgeted.
+- **A cardinality/cost budget exists.** Observability without a cost ceiling becomes the surprise invoice.
+- **Dashboards are defined by the question they answer**, not by quantity.
+
+## When to use this skill
+
+- ✅ Standing up monitoring/SLOs for a new or existing service
+- ✅ "What should we measure / alert on?" / designing an alerting strategy
+- ✅ Fixing alert fatigue — too many pages, most non-actionable
+- ✅ Turning `nfr-spec`'s observability requirement into an implementable plan
+
+## When NOT to use this skill
+
+- ❌ Business/product success metrics — that's `success-metrics`
+- ❌ Customer/stakeholder comms during an outage — that's `incident-comms`
+- ❌ The post-incident analysis — that's `postmortem-generator`
+- ❌ The one-line observability *requirement* in a spec — that's `nfr-spec`; this is the full design beneath it
+
+## Anti-patterns to avoid
+
+- ❌ **Resource metrics as SLOs.** Alerting on CPU/memory/disk as if they were user pain — they auto-recover, they spike harmlessly, and they page you at 3am for nothing while the actual user-facing error goes unnoticed.
+- ❌ **Averages for latency.** "Average response 120ms" with a p99 of 4s means a lot of users are suffering invisibly. Measure the percentile and the threshold.
+- ❌ **Cause-based paging.** A page for every component hiccup. Page on the symptom (users hurt / budget burning fast); let causes inform diagnosis, not wake people.
+- ❌ **The alert with no runbook.** Firing a page that says "high error rate" with no "here's what to check" — that's a puzzle handed to someone half-asleep.
+- ❌ **Unbounded metric cardinality.** `user_id` or `request_id` as a metric label — millions of time series, a five-figure bill, and a dashboard that times out. Those belong in logs/traces.
+- ❌ **String-soup logs.** Unstructured `printf` logs you can't query or aggregate, retained forever at full volume. Structure them, sample the hot path, budget the retention.
+- ❌ **The 100-graph dashboard.** Built to look thorough, used by no one, because no panel answers a question anyone asks under pressure.
+- ❌ **99.99% by reflex.** Copying a target off a blog instead of from the down-for-an-hour cost calibration; every nine multiplies the engineering and on-call burden.

package/skills/observability-plan/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "observability-plan",
+  "version": "0.1.0",
+  "description": "Design an observability plan for a service — user-journey SLIs, SLOs with error budgets, symptom-based burn-rate alerting (page vs ticket, every page actionable and runbook-linked), and a deliberate metrics/logs/traces split with a cardinality and cost budget. Use when the user needs SLOs, alerting design, a monitoring/observability strategy, dashboards, or wants to fix alert fatigue and know what to measure.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["capacity-cost-model", "incident-comms", "nfr-spec", "postmortem-generator", "runbook-generator", "success-metrics"],
+  "tags": ["observability", "slo", "sli", "alerting", "monitoring", "sre"],
+  "model": { "tier": "standard", "rationale": "Methodology synthesis against fixed SRE practices (golden signals, burn-rate alerting, pillar split). SLO calibration needs judgment but is bounded; escalate via ambiguous-input on contested reliability targets." }
+}

package/skills/observability-plan/reference.md

@@ -0,0 +1,67 @@
+# observability-plan reference — signals, SLO math, burn-rate alerts, pillar split
+
+## The golden signals (cover all four; they're cause/saturation signals, not SLOs by default)
+
+| Signal | Question | Typical measure |
+|---|---|---|
+| **Latency** | how slow? (split success vs error latency) | p50/p95/p99 against a threshold |
+| **Traffic** | how much demand? | rps, requests/min, active connections |
+| **Errors** | how often failing? | error rate, by class (5xx vs 4xx) |
+| **Saturation** | how full? | CPU/mem/queue depth/connection-pool % — the leading indicator of trouble |
+
+User-facing **latency + errors** usually become SLIs; **saturation** is the early-warning/cause signal that informs diagnosis, not the page.
+
+## SLI types (good events / valid events, from the user's side)
+
+| SLI | Definition | Measured where |
+|---|---|---|
+| Availability | successful responses / valid requests | LB / gateway / client |
+| Latency | requests faster than threshold / valid requests | same vantage as the user |
+| Freshness | data served within max staleness / reads | for caches, pipelines, replicas |
+| Correctness | correct outputs / total (where checkable) | post-processing validation |
+| Throughput | jobs completed within deadline / scheduled | batch/streaming |
+
+Measure as close to the user as practical. An SLI measured server-side misses the failures that never reached the server.
+
+## SLO targets, windows, error budgets
+
+- Target over a **rolling window** (28 or 30 days is common). 99.9%/28d ≈ **40 min** of budget; 99.95% ≈ 20 min; 99.99% ≈ 4 min.
+- The **error budget** = (1 − SLO) × window. It is the allowed unreliability — spend it on releases and risk.
+- **Error-budget policy** (write it): e.g. "budget >50% remaining → ship freely; <25% → freeze risky changes, prioritize reliability; exhausted → release freeze until recovered." Without a policy, the SLO doesn't change any behavior.
+- Calibrate targets to cost (see `nfr-spec` down-for-an-hour). Internal tools rarely need >99.5%; payment paths may justify 99.95%+. Each nine is ~10× the effort.
+
+## Multi-window, multi-burn-rate alerting (page on fast burn, ticket on slow)
+
+"Burn rate" = how fast you're consuming the error budget relative to even consumption (1× burn would exactly exhaust it at window end). Alert on high burn over a short window AND confirm over a longer one to avoid flapping.
+
+| Burn rate | Budget consumed | Long/short windows | Severity |
+|---|---|---|---|
+| 14.4× | 2% in 1h | 1h and 5m both breaching | 🔴 page — fast burn, acute |
+| 6× | 5% in 6h | 6h and 30m | 🟠 page — sustained |
+| 3× | 10% in 1d | 1d and 2h | 🟡 ticket — slow burn |
+| 1× | tracking only | — | dashboard, no alert |
+
+Require both the long and short window to breach before firing — the short window confirms it's still happening, the long window confirms it's significant. This is what replaces brittle "errors > N" static thresholds.
+
+## Alert-quality rules
+
+1. **Every page is actionable now** — there is a thing a human does on receipt. If not, it's a ticket.
+2. **Every page maps to a runbook entry** (→ `runbook-generator`). No runbook = not ready to page.
+3. **Page on symptoms** (SLO burn, user-facing errors), not causes (a pod restarted). Causes are diagnostic context.
+4. **Deduplicate and group** — one incident, one page, not 200 per-host alerts.
+5. **Tier severity:** page (wake someone) / ticket (next business day) / log (queryable, no notification). Most "alerts" should be tickets or logs.
+6. **Review noisy/non-actionable pages** monthly; a page that's been ignored 5× is either re-tiered or fixed. Alert fatigue is a reliability risk in itself.
+
+## Metrics vs logs vs traces (use each for its strength)
+
+| | Metrics | Logs | Traces |
+|---|---|---|---|
+| Good at | aggregate state, alerting, SLOs | per-event detail, debugging one request | request flow across services |
+| Cost driver | **cardinality** (label combinations) | **volume** (GB ingested) | sampling rate × span count |
+| Cardinality | keep LOW — bounded labels only | high-cardinality lives here | high-cardinality lives here |
+| Retention | long (cheap, downsampled) | short, sampled on hot path | short, tail-sampled on errors/slow |
+| Don't | put user_id/request_id as a label | use as a metric (count via logs = $$$) | sample blindly and miss the error traces |
+
+**Cardinality budget:** allowed metric labels are bounded sets — `region`, `status_class`, `endpoint_template`, `tenant_tier`. Forbidden as metric labels — `user_id`, `request_id`, raw `url`, `email`. Those identifiers belong in logs/traces, linked from metrics via **exemplars**. One unbounded label can create millions of series and a five-figure monthly bill.
+
+**Structured logs:** key-value/JSON, consistent field names, a trace/correlation ID on every line so logs join to traces. Sample the hot path (keep all errors, sample successes). Set a retention budget (ties to `capacity-cost-model`).

package/skills/observability-plan/templates/observability-plan.md

@@ -0,0 +1,62 @@
+# Observability-plan template
+
+SLIs from the user's side, SLOs with budgets and a policy, pages that are actionable and runbook-linked, pillars split by purpose with a cost ceiling.
+
+```markdown
+# Observability plan: {service}
+
+**Date:** {YYYY-MM-DD} · **On-call team:** {role}
+
+## Critical user journeys (SLIs measure these)
+
+| Journey | "Down" means to a user | SLI |
+|---|---|---|
+| {log in} | {can't authenticate} | success rate of auth requests |
+| {place order} | {checkout errors / hangs} | % checkout req 2xx within 1s |
+
+## SLIs / SLOs / error budgets
+
+| SLI | Definition (good/valid) | SLO (target / window) | Error budget | Measured at |
+|---|---|---|---|---|
+| checkout availability | 2xx / valid checkout req | 99.9% / 28d | ~40 min/28d | load balancer |
+| checkout latency | < 1s / valid checkout req | 99% < 1s / 28d | 1% of checkout req/28d may exceed 1s | load balancer |
+
+**Error-budget policy:** {>50% remaining → ship freely; <25% → freeze risky releases; exhausted → release freeze + reliability focus until recovered}.
+
+## Alerts (symptom-based, burn-rate, every page runbook-linked)
+
+| Alert | Condition | Windows | Burn | Page / Ticket | Runbook |
+|---|---|---|---|---|---|
+| checkout fast burn | budget burn ≥ 14.4× | 1h & 5m | acute | 🔴 page | runbook#checkout-errors |
+| checkout slow burn | budget burn ≥ 3× | 1d & 2h | slow | 🟡 ticket | runbook#checkout-degraded |
+| saturation early-warn | pool util > 85% | 15m | — | 🟡 ticket | runbook#scale-checkout |
+
+{No page without a runbook link. Cause/resource signals are tickets or dashboards, not pages.}
+
+## Three-pillar strategy
+
+| Pillar | Used for | Key rules |
+|---|---|---|
+| Metrics | SLOs, alerts, golden signals | bounded labels only (region, status_class, endpoint_template) |
+| Logs | per-request debugging | structured JSON, trace-id on every line, sample successes, keep errors, retention {N}d |
+| Traces | cross-service latency/error attribution | propagate context all hops, tail-sample errors/slow, {x}% baseline |
+
+## Cardinality & cost budget
+
+- **Allowed metric labels:** {region, status_class, endpoint_template, tenant_tier}
+- **Forbidden as metric labels (→ logs/traces):** user_id, request_id, raw url, email
+- **Budgets:** metric series ≤ {N}; log ingest ≤ {GB/day}; trace sampling {x}%. Alert at 80% of each. (→ `capacity-cost-model`)
+
+## Dashboards (by the question each answers)
+
+| Dashboard | Question it answers | Panels |
+|---|---|---|
+| Service health | "is checkout healthy right now?" | golden signals + SLO/budget status |
+| Checkout drill-down | "where is the latency/error coming from?" | per-dependency latency, error breakdown, trace exemplars |
+
+## Instrumentation conventions
+
+- Metric naming: {namespace.subsystem.unit} (e.g. `checkout.request.duration_ms`)
+- Trace context propagated on every hop ({W3C traceparent}); exemplars link metrics → traces.
+- Every new feature ships its SLI instrumentation with it (not as a fast-follow).
+```

package/skills/okr-cascade/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: okr-cascade
+description: Cascade company OKRs to team-level OKRs — with a gap registry for objectives no team credibly owns, and a causal metric tree connecting each team KR to the north-star it's supposed to move. Use when the user wants to set or cascade OKRs, align team goals to company goals, "turn strategy into quarterly objectives", or audit existing OKRs for gaps and vanity metrics.
+---
+
+# okr-cascade
+
+Turns company objectives into team OKRs that actually roll up — and surfaces what a cascade usually hides: the objectives nobody credibly owns (the **gap registry**) and the KRs that count activity instead of causing outcomes (the **causal metric tree**). Org-level counterpart to `success-metrics`, which owns feature-level measurement — this skill decides *what the teams aim at*; `success-metrics` designs how one feature proves it moved a KR.
+
+## How to respond
+
+1. **Get the company OKRs and the cycle.** From the input or by asking (at most 2 questions, spent on: *"what are the company's top 3–5 objectives this cycle, verbatim?"* and *"which teams are in scope?"*). Record company OKRs **verbatim** — rewriting the company's words without saying so corrupts the roll-up. No company objectives exist at all → stop; that's a strategy conversation (`strategy-analysis`), not a cascade. Non-interactive run (no user to ask): an unstated cycle or team list gets assumed and tagged `[assumption]`; absent company OKRs are never invented — emit `BLOCKED: need the company OKRs, verbatim — rerun with the top 3–5 objectives, their KRs, and the teams in scope` instead.
+
+2. **Grade the company KRs before cascading them.** Each company KR is either an **outcome** (a customer or business result: retention, revenue, time-to-value) or an **output** (a thing shipped: "launch v2", "migrate to k8s"). Outputs at company level get flagged with the outcome they presumably serve — ✅ *"'Launch self-serve onboarding' → presumably serves activation rate; recommend restating as the activation target"*. Cascading an output produces teams that hit every KR while the business stands still.
+
+3. **Derive team OKRs per company objective.** For each in-scope team: an objective (qualitative, motivating, this-cycle) and 2–4 KRs that are (a) **measurable at the team's scope** — the team's work moves the number without needing three other teams to also succeed; (b) **causally upstream** of a company KR, with the causal sentence written out: ✅ *"Cut p95 checkout latency to 800ms — slow checkout is the top named cause of cart abandonment `[data: support tags]`, which feeds company KR 'checkout conversion +2pp'"*; (c) **scored 0.0–1.0 at cycle end** — a KR that can only be "done/not done" is a task wearing a KR's clothes. Not every team maps to every objective — forcing it manufactures alignment theater; a team with no credible contribution to an objective simply doesn't appear under it.
+
+4. **Build the gap registry.** A gap is a company objective or KR with **no team-level expression** after step 3 — no owner, no credible path, or a current-vs-target delta no in-scope team can close. Name each gap (kebab-case slug), state which company KR it starves, and rank gaps by the weight of the objective they block. The registry is a first-class output: a cascade with zero gaps on the first pass usually means step 3 was generous, not that the org is perfectly shaped — say so if it happens.
+
+5. **Draw the causal metric tree.** North-star (the one user-behavioral outcome metric capturing this cycle's most strategic objective — never "features shipped") at the root; each team KR attached at its causal position as a leading indicator; each edge carrying its causal sentence. A KR that can't be attached to the tree is either a guardrail (label it) or measurement theater (cut it, and say which). No credible north-star derivable → report that as the cascade's top finding and recommend naming one before committing OKRs.
+
+6. **Emit with [`templates/okr-cascade.md`](templates/okr-cascade.md)** in one message: company OKRs (verbatim, with output-KR flags), team OKRs with causal sentences, ranked gap registry, metric tree (Mermaid `flowchart` — north-star at root, KRs as leaves), and next steps: each team KR needing full measurement design → `success-metrics`; each gap needing a decision → the owner who must staff or explicitly drop it.
+
+## Useful references in this skill
+
+- [`templates/okr-cascade.md`](templates/okr-cascade.md) — cascade tables, gap registry, and metric-tree skeleton
+
+## Quality bar
+
+- **Company OKRs appear verbatim**, and every restated one is marked as restated with the reason.
+- **Every team KR has its causal sentence** naming the company KR it feeds and the mechanism. "Aligns with company goals" is not a mechanism.
+- **Every team KR is scorable 0.0–1.0** and measurable at the team's own scope. Binary deliverables are tasks — they can live under a KR, not as one.
+- **Output KRs are flagged** at every level, each with the outcome it presumably serves.
+- **The gap registry is present and ranked** — even when its honest content is "none found; here's why that's suspicious".
+- **The metric tree has one north-star**, and every KR is attached, labeled guardrail, or explicitly cut.
+
+## When to use this skill
+
+- ✅ "Cascade our company OKRs to the platform/growth/mobile teams"
+- ✅ Quarterly planning: turning strategy into team objectives
+- ✅ Auditing existing OKRs — which are vanity, which roll up nowhere
+- ✅ "Leadership set five objectives; which have no owner?"
+
+## When NOT to use this skill
+
+- ❌ Measuring one feature's success — `success-metrics` (it declares org OKRs out of scope; this skill returns the favor)
+- ❌ No strategy exists to cascade — `strategy-analysis` or `prfaq` first
+- ❌ Sprint/backlog prioritization — OKRs are aims, not a work queue
+- ❌ Individual performance goals — cascading OKRs to persons turns a steering tool into a rating tool, and both break
+
+## Anti-patterns to avoid
+
+- ❌ **Cascading outputs.** "Company: launch v2 → Team: ship 12 features" — everyone hits 100% while retention falls. Flag outputs at intake or inherit the disease.
+- ❌ **Alignment theater.** Every team forced under every objective, with prose doing the aligning that causality can't. Empty cells are information.
+- ❌ **Vanity KRs.** Page views, sign-ups, story points. If the number can improve while the business doesn't, it can't be a KR.
+- ❌ **A gapless first pass.** The registry exists because real orgs have orphaned objectives — a clean sheet means the bar in step 3 slipped.
+- ❌ **KR-as-task-list.** "Complete the migration" scores 0 or 1 and measures effort. What outcome does the migration purchase? That's the KR.
+- ❌ **Metric list instead of metric tree.** "DAU, NPS, churn, revenue" with no causal positions is a dashboard inventory, not a tree — every node needs its edge.
+- ❌ **Silent rewording of company OKRs.** Improving leadership's phrasing without marking it breaks the roll-up contract and hides a real disagreement worth surfacing.

package/skills/okr-cascade/evals/eval_queries.json

@@ -0,0 +1,12 @@
+[
+  { "query": "Cascade our company OKRs down to team level", "should_trigger": true },
+  { "query": "Help me set quarterly OKRs for the platform team that align to company goals", "should_trigger": true },
+  { "query": "Audit our existing OKRs — which ones are vanity metrics?", "should_trigger": true },
+  { "query": "Leadership set five objectives; which have no team owner?", "should_trigger": true },
+  { "query": "Turn our strategy into Q4 objectives for the org", "should_trigger": true },
+
+  { "query": "How do we know this feature worked? Define its success metrics", "should_trigger": false },
+  { "query": "Prioritize our sprint backlog for next iteration", "should_trigger": false },
+  { "query": "Run a SWOT on our market position", "should_trigger": false },
+  { "query": "Set performance goals for my direct reports", "should_trigger": false }
+]

package/skills/okr-cascade/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "okr-cascade",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Cascade these company OKRs to our three teams (platform, growth, mobile). O1: Become the default choice for mid-market DevOps teams — KR1: net revenue retention 115%, KR2: launch the v2 platform. O2: Operational excellence — KR1: 99.95% availability. Cycle: Q4.",
+      "assertions": [
+        "Company OKRs appear verbatim; 'launch the v2 platform' is flagged as an output KR with the outcome it presumably serves",
+        "Each team KR has a written causal sentence naming the company KR it feeds and the mechanism",
+        "Each team KR has baseline → target and is scorable 0.0–1.0 — no binary 'complete the migration' KRs",
+        "Not every team is forced under every objective — teams with no credible contribution are omitted from that objective",
+        "A ranked gap registry is present (or explicitly states none found and why that is suspicious)",
+        "A causal metric tree with exactly one north-star is emitted; every team KR is attached, labeled guardrail, or explicitly cut",
+        "The north-star is user-behavioral, not 'features shipped' or another output",
+        "Next steps route team KRs to success-metrics for measurement design and gaps to a named decision owner"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "[Non-interactive run — no user available to answer questions] Cascade our OKRs to the teams.",
+      "assertions": [
+        "No company OKRs are invented — the output is BLOCKED: need the company OKRs, verbatim",
+        "The BLOCKED output states what to rerun with (the top 3-5 objectives and their KRs, plus teams in scope)",
+        "No cascade tables, gap registry, or metric tree appear"
+      ]
+    }
+  ]
+}

package/skills/okr-cascade/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "okr-cascade",
+  "version": "0.1.0",
+  "description": "Cascade company OKRs to team-level OKRs — with a gap registry for objectives no team credibly owns, and a causal metric tree connecting each team KR to the north-star it's supposed to move. Use when the user wants to set or cascade OKRs, align team goals to company goals, \"turn strategy into quarterly objectives\", or audit existing OKRs for gaps and vanity metrics.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["prfaq", "strategy-analysis", "success-metrics"],
+  "tags": ["okr", "goals", "alignment", "north-star", "metric-tree", "quarterly-planning"],
+  "model": { "tier": "standard", "rationale": "Structured derivation against a fixed roll-up discipline; the causal-sentence and gap judgments need care but the template bounds them. Escalate via ambiguous-input when the company objectives themselves are contested." }
+}

package/skills/okr-cascade/templates/okr-cascade.md

@@ -0,0 +1,46 @@
+# OKR Cascade — {cycle, e.g. 2026 Q4}
+
+> Teams in scope: {list} · Source of company OKRs: {doc/person} · Status: DRAFT
+
+## Company OKRs (verbatim)
+
+### O1: {objective, verbatim}
+| KR | Type | Note |
+|---|---|---|
+| {KR verbatim} | outcome / **output ⚠** | {if output: the outcome it presumably serves} |
+
+## Team OKRs
+
+### Team: {name}
+
+**O: {team objective — qualitative, motivating, this cycle}** _(feeds company O1)_
+
+| KR | Baseline → Target | Causal sentence (mechanism → company KR) | Scoring |
+|---|---|---|---|
+| {KR} | {x → y} | {why moving this moves company KR n} | {how 0.0–1.0 is graded, e.g. linear on pp gained} |
+
+<!-- A team with no credible contribution to an objective doesn't appear under it. -->
+
+## Gap registry (ranked)
+
+| # | Gap slug | Company KR or objective it starves | Why no team covers it | Decision needed from |
+|---|---|---|---|---|
+| 1 | {kebab-slug} | {KR, or "On (objective-level)"} | {no owner / no credible path / delta too large} | {role} |
+
+## Causal metric tree
+
+North-star: **{one user-behavioral outcome metric}**
+
+```mermaid
+flowchart BT
+    KR1["{team KR}"] -->|{causal sentence, short}| NS["{north-star}"]
+    KR2["{team KR}"] -->|{…}| NS
+    G1["{guardrail KR}"] -.->|guardrail| NS
+```
+
+Cut from the tree: {KRs that attached nowhere, and why} — or "none".
+
+## Next steps
+
+- {team KR} → run `success-metrics` for full measurement design (baseline, counter-metric, instrumentation)
+- {gap slug} → {owner role} staffs it or explicitly drops it by {date}