skilldrop-cli 0.2.0

package/skills/sonar-review/lenses/vulnerabilities.md

@@ -0,0 +1,52 @@
+# Lens 2 — Vulnerabilities
+
+Sonar's **Vulnerability** category is code where **Sonar is confident an attacker can exploit it**: injection, weak crypto, hard-coded secrets, broken auth flows, unsafe deserialization. Different from **Hotspots** (lens 3) — Hotspots are "this *could* be unsafe, a human needs to look"; Vulnerabilities are "this *is* unsafe by the catalog's definition".
+
+Every Vulnerability on new code is a **gate failure** under the default Sonar way. Treat as merge-blocking.
+
+## What you're looking at
+
+Pull the issues list, filter to `type=VULNERABILITY`, intersect with changed files. Common rule families:
+
+| Family | Example IDs | What it catches |
+|---|---|---|
+| SQL injection | `javascript:S3649`, `java:S3649`, `python:S3649` | String-concatenated queries |
+| Command injection | `S2076`, `S4036` | `exec(\`tar ${user}\`)`, `Runtime.exec(userInput)` |
+| Path traversal | `S2083`, `S6549` | `fs.readFile(userInput)` without normalization |
+| XSS | `javascript:S5247`, `S5131` | `innerHTML = userInput`, unescaped template output |
+| SSRF | `S5144` | HTTP client URL built from user input |
+| Hard-coded secrets | `S6418`, `S2068` | API keys, passwords, tokens in source |
+| Weak crypto | `S2278`, `S5547`, `S4790` | MD5/SHA1 for auth, ECB mode, deprecated TLS |
+| Insecure cookie | `S2092`, `S3330` | `httpOnly: false`, missing `secure` flag |
+| Open redirect | `javascript:S5146` | `res.redirect(userInput)` |
+| Unsafe deserialization | `S5135` | `pickle.loads(network_bytes)`, Java `ObjectInputStream` |
+| Permissive CORS | `S5122` | `Access-Control-Allow-Origin: *` with credentials |
+
+Every Vulnerability rule is tagged with **CWE** and (where applicable) **OWASP Top 10** identifiers — surface these in the finding so the user can map to compliance frameworks.
+
+## How to phrase each finding
+
+1. **Where** — `file:line` + the offending expression. Quote enough to make the data flow obvious.
+2. **Rule + category + standards tags** — `[VULNERABILITY · javascriptsecurity:S3649 · CWE-89 · OWASP A03:2021] SQL injection`.
+3. **Why it matters** — describe the **exploit path**, not the rule. ✅ "`userId` flows from `req.params.id` into the SQL string at line 42 without escaping — an attacker can send `1 OR 1=1` and read every row of the table." ❌ "Possible SQL injection."
+4. **Fix** — concrete and **the right one**:
+   - SQL injection → parameterized query / prepared statement, with a code snippet using the project's existing DB client. Quote the right call from elsewhere in the codebase if available.
+   - Command injection → `execFile(cmd, [args])` not `exec(cmd + args)`; never `shell: true` with user data.
+   - XSS → contextual escaping (text vs attribute vs URL vs JS), or the framework's safe primitive (`.textContent` not `.innerHTML`; `{}` not `{{{}}}`).
+   - Hard-coded secret → move to env/secret manager, **rotate the leaked value**, and call out the rotation explicitly — finding it in source means it was committed and is in git history.
+   - Weak crypto → name the replacement algorithm (e.g. `SHA-256 + HMAC`, `bcrypt/argon2`, `AES-256-GCM`).
+
+## Calibration
+
+- **BLOCKER vulnerability** — direct injection / hard-coded prod credential / known-broken crypto on auth. Stop the merge; in some cases stop the deploy (rotate creds, audit access).
+- **CRITICAL vulnerability** — exploit requires a slightly less trivial path (chained, requires auth, narrow window). Fix before merge.
+- **MAJOR vulnerability** — defense-in-depth issue (missing flag, weak default). Fix before merge if reasonable.
+
+Do not down-grade these. If you think Sonar is wrong, mark it for the user to dispute via the Sonar UI (`Resolve as won't fix` / `false positive`) — don't silently drop it from the report.
+
+## Anti-patterns when reporting Vulnerabilities
+
+- ❌ Suggesting input validation as the fix for injection. Validation is defense in depth; **parameterization** is the fix. ❌ "Validate the user ID looks like a number." ✅ "Use `db.query('SELECT * FROM users WHERE id = $1', [userId])` — never concatenate."
+- ❌ Forgetting the rotation step on a leaked secret. If a key was in source, it leaked; "remove the line" without "rotate the value" leaves the exposure live.
+- ❌ Listing the rule's CWE without using it. The CWE tag is for the user's report, not your decoration — include it so they can answer "is this our SOC 2 finding?".
+- ❌ Recommending the user mark it "won't fix" to pass the gate. The gate is the point. If it's truly a false positive, the resolution path is via the Sonar UI's `false positive` workflow, with a comment — not a CI-bypass.

package/skills/sonar-review/manifest.json

@@ -0,0 +1,37 @@
+{
+  "name": "sonar-review",
+  "version": "0.1.0",
+  "description": "Run a Sonar scan against the just-changed code on the current branch and produce a structured compliance report — quality-gate verdict (PASS / FAIL), then severity-tagged findings (🟥 blocker / 🟧 critical / 🟨 major / ⚪ minor / ⚪ info) scoped to changed files, each with file:line, the Sonar rule ID, the category (bug / vulnerability / security hotspot / code smell), why it matters, and a concrete fix. Works against both **SonarQube server** (self-hosted) and **SonarCloud** (SaaS) — mode is detected from `sonar-project.properties`. Sister skill to `devils-advocate`, but enforces Sonar's rule catalog and the project's quality gate rather than a hand-rolled lens sweep. Use after writing code, before pushing or opening a PR, when the user says \"is this Sonar-compliant?\", \"run Sonar on this\", \"will the quality gate pass?\", or any pre-merge compliance check.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [
+      "SONAR_TOKEN"
+    ],
+    "optional": [
+      "SONAR_HOST_URL"
+    ]
+  },
+  "related": [
+    "devils-advocate",
+    "sonar-onboard"
+  ],
+  "tags": [
+    "sonarqube",
+    "sonarcloud",
+    "sonar",
+    "code-quality",
+    "review",
+    "quality-gate",
+    "compliance",
+    "security",
+    "dev-workflow"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Formats Sonar API findings into a report. The hard analysis is Sonar's; this is synthesis. Escalates on very large diffs."
+  }
+}

package/skills/sonar-review/reference.md

@@ -0,0 +1,167 @@
+# sonar-review — reference
+
+Long-form material that doesn't belong in `SKILL.md`.
+
+## SonarQube server vs SonarCloud — what changes for this skill
+
+Almost nothing. The API endpoints used here (`/api/qualitygates/project_status`, `/api/issues/search`, `/api/hotspots/search`) are identical in shape on both, authenticated the same way (`Authorization: Bearer $SONAR_TOKEN` or basic auth with the token as username). Only the host differs:
+
+| Mode | `$SONAR_HOST` |
+|---|---|
+| SonarQube server | `$SONAR_HOST_URL` (from env) |
+| SonarCloud | `https://sonarcloud.io` (fixed) |
+
+Mode is detected from `sonar-project.properties` — presence of `sonar.organization=<key>` means SonarCloud; absence means server. Don't ask the user; the properties file is canonical.
+
+Two behaviors that *do* differ:
+
+- **Branch analysis** — SonarCloud supports branch + PR analysis on all tiers. SonarQube Community Edition does not. If you set `sonar.branch.name` and the server returns `License not valid for branch analysis`, you're on Community Edition. Re-run without the flag; the scan will overwrite the default-branch history, which is acceptable for a local pre-merge check but not for CI.
+- **PR decoration** — SonarCloud auto-decorates the PR with findings if `GITHUB_TOKEN` is in the workflow env. Self-hosted needs ALM integration set up server-side. This skill doesn't touch PR decoration, but if the user asks why findings aren't appearing on the PR even though the scan ran, it's usually this.
+
+## SonarQube API shapes you'll parse
+
+### `/api/qualitygates/project_status`
+
+```json
+{
+  "projectStatus": {
+    "status": "ERROR",  // or "OK"
+    "conditions": [
+      {
+        "status": "ERROR",
+        "metricKey": "new_coverage",
+        "comparator": "LT",
+        "errorThreshold": "80",
+        "actualValue": "71.4"
+      },
+      {
+        "status": "OK",
+        "metricKey": "new_bugs",
+        "comparator": "GT",
+        "errorThreshold": "0",
+        "actualValue": "0"
+      }
+    ]
+  }
+}
+```
+
+`status` is the gate verdict (`OK` / `ERROR`). `conditions` is the per-rule breakdown — list the `ERROR` ones in the report's gate-conditions table.
+
+### `/api/issues/search`
+
+```json
+{
+  "issues": [
+    {
+      "key": "AYz1...",
+      "rule": "javascript:S2259",
+      "severity": "CRITICAL",
+      "type": "BUG",
+      "component": "myorg_payments:src/api/checkout.ts",
+      "line": 47,
+      "message": "Refactor this code to not use null dereference.",
+      "status": "OPEN",
+      "tags": ["cwe"]
+    }
+  ],
+  "paging": { "total": 42, "pageIndex": 1, "pageSize": 100 }
+}
+```
+
+`component` includes the project key prefix — strip it to get the file path. `severity` is one of `BLOCKER` / `CRITICAL` / `MAJOR` / `MINOR` / `INFO`. `type` is one of `BUG` / `VULNERABILITY` / `CODE_SMELL` (hotspots come from a different endpoint).
+
+### `/api/hotspots/search`
+
+```json
+{
+  "hotspots": [
+    {
+      "key": "AYz2...",
+      "component": "myorg_payments:src/jobs/export.ts",
+      "line": 28,
+      "ruleKey": "javascript:S2076",
+      "vulnerabilityProbability": "HIGH",  // HIGH / MEDIUM / LOW — maps to review priority
+      "status": "TO_REVIEW",                // TO_REVIEW / REVIEWED
+      "message": "Make sure that executing this OS command is safe here."
+    }
+  ]
+}
+```
+
+Hotspots **don't** appear in `/api/issues/search`. Forgetting to call this endpoint silently drops the security-hotspot lens.
+
+## Maven / Gradle / dotnet wrappers
+
+If `sonar-project.properties` references the standalone scanner but the project has `pom.xml`, `build.gradle`, or a `.sln`, prefer the language-native wrapper — it hooks into the compile step and produces better analysis:
+
+| Project type | Command |
+|---|---|
+| Maven | `mvn -B verify sonar:sonar -Dsonar.host.url=$SONAR_HOST_URL -Dsonar.token=$SONAR_TOKEN` |
+| Gradle | `./gradlew build sonar -Dsonar.host.url=$SONAR_HOST_URL -Dsonar.token=$SONAR_TOKEN` |
+| .NET | `dotnet sonarscanner begin /k:"<key>" /d:sonar.host.url=$SONAR_HOST_URL /d:sonar.token=$SONAR_TOKEN` → `dotnet build` → `dotnet sonarscanner end /d:sonar.token=$SONAR_TOKEN` |
+
+The standalone `sonar-scanner` still works for these but won't see compile-time information (type resolution, framework attributes). Findings will be shallower.
+
+## Scoping to PR diff
+
+The skill scopes the **report** to changed files, not the scan itself. To compute the changed files:
+
+```bash
+# vs origin/main (most PRs)
+git diff --name-only origin/main...HEAD
+
+# vs the previous commit (just-pushed work)
+git diff --name-only HEAD~1
+```
+
+When filtering issues, normalize the Sonar `component` field (`<projectKey>:<path>`) against your diff list. Strip the project-key prefix; compare paths.
+
+**Don't filter the scan**. `sonar-scanner` analyzes the whole project because cross-file analysis (call graphs, import resolution) requires it. You filter the *findings* on the way out.
+
+## Running against the SonarQube server with `branch` analysis
+
+The SonarQube Developer Edition+ supports branch analysis natively — pass `-Dsonar.branch.name=<branch>`. Community Edition does **not**. If the Sonar server returns:
+
+```
+ERROR: License not valid for branch analysis. Branches will not be analyzed.
+```
+
+… the project is on Community Edition. Workarounds:
+
+- Use the **`sonar.projectVersion`** trick — set `projectVersion=<branch>` to get separate histories per branch (crude but works on CE).
+- Scan only on merge to `main` (PR-time scanning unavailable on CE).
+- Upgrade to Developer Edition if branch analysis is required.
+
+Document the edition limitation in the report — don't pretend the missing branch view is a configuration issue.
+
+## Polling the scan task
+
+`sonar-scanner` returns once it uploads to the server, but the gate isn't computed until the server processes the task. After the scanner finishes:
+
+```bash
+TASK_URL=$(grep '^ceTaskUrl=' .scannerwork/report-task.txt | cut -d= -f2-)
+
+# Poll until status=SUCCESS (or FAILED)
+while true; do
+  STATUS=$(curl -s -u "$SONAR_TOKEN:" "$TASK_URL" | jq -r '.task.status')
+  case "$STATUS" in
+    SUCCESS) break ;;
+    FAILED|CANCELED) echo "Scan task failed: $STATUS"; exit 1 ;;
+    *) sleep 5 ;;
+  esac
+done
+```
+
+Skipping this means the gate API returns stale data from the *previous* scan, not this one. Always poll.
+
+## Common false positives worth knowing
+
+| Rule | Common false positive | What to do |
+|---|---|---|
+| `javascript:S2068` (hard-coded password) | Variable named `password` in a Zod/Joi schema definition | Mark `false positive` in Sonar UI |
+| `python:S5689` (use of `eval`) | `ast.literal_eval` (safe) flagged alongside `eval` | Confirm `literal_eval`, ignore |
+| `java:S3776` (cognitive complexity) | Big `switch` over an enum | Extract per-case handlers if it improves things; otherwise dispute |
+| `csharpsquid:S1135` (TODO comment) | TODOs intentionally tracked in code | Roll up the count, don't list each |
+
+These are dispositions to suggest, **not** to apply silently. The user marks them in Sonar UI; you surface them in the report so they know which to look at.

package/skills/sonar-review/templates/report.md

@@ -0,0 +1,84 @@
+# Sonar review: {feature / PR title}
+_Scope: {N changed files, M lines added/removed} · Branch: `{branch}` · Scanned: {YYYY-MM-DD HH:MM} · Scan duration: {Ns}_
+_Sonar project: [`{project-key}`]({sonar-host}/dashboard?id={project-key}&branch={branch})_
+
+## Quality gate
+
+**{✅ PASS / ❌ FAIL}** — {one-line reason — what failed (or "all conditions met")}
+
+{2–3 sentence summary. Lead with what failed the gate. If PASS, say so plainly and call out the closest condition to the line.}
+
+### Gate conditions
+
+| Condition | Actual | Threshold | Status |
+|---|---|---|---|
+| New bugs | {N} | 0 | ✅ / ❌ |
+| New vulnerabilities | {N} | 0 | ✅ / ❌ |
+| New security hotspots reviewed | {pct}% | 100% | ✅ / ❌ |
+| Coverage on new code | {pct}% | ≥ 80% | ✅ / ❌ |
+| Duplicated lines on new code | {pct}% | ≤ 3% | ✅ / ❌ |
+
+(Drop rows the project's gate doesn't enforce.)
+
+## Findings on changed code
+
+| Severity | Bugs | Vulnerabilities | Hotspots | Code smells |
+|---|---|---|---|---|
+| 🟥 Blocker | {N} | {N} | — | {N} |
+| 🟧 Critical | {N} | {N} | {N} | {N} |
+| 🟨 Major | {N} | {N} | {N} | {N} |
+| ⚪ Minor | {N} | — | — | {N} |
+| ⚪ Info | {N} | — | — | {N} |
+
+### 1. Bugs
+
+{For each finding:}
+
+#### 🟥 [`javascript:S2259`] TypeError on null dereference
+- **Where:** `src/api/checkout.ts:47` — `discount.amount`
+- **Why it matters:** When `discount=null` reaches line 47, `applyDiscount` throws `TypeError` — the request returns a 500, not a graceful "no discount applied".
+- **Fix:** Add `if (discount == null) return 0;` at the top of `applyDiscount`, matching the pattern in `applyTax` at line 102.
+
+{If no findings: "No bugs flagged on changed code."}
+
+### 2. Vulnerabilities
+### 3. Security hotspots
+
+{Hotspots are review-required, not auto-fix. Each one:}
+
+#### 🟧 [`javascript:S2076`] OS command construction from user input
+- **Where:** `src/jobs/export.ts:28` — `exec(\`tar -czf ${userPath}\`)`
+- **Why it matters:** `userPath` flows from the export API without escaping — if an attacker controls the export name, they can inject shell metacharacters.
+- **Evidence for review:** `userPath` is validated upstream in `validateExportName` (`src/api/exports.ts:14`) to match `/^[a-zA-Z0-9_-]+$/` — that *should* make injection impossible, but the validation runs in a separate process and the variable name is reused.
+- **Action:** Mark **Safe** if you confirm the upstream validation is enforced on every code path that hits this exec; otherwise mark **At Risk** and switch to `execFile` with an args array.
+
+### 4. Code smells
+### 5. Coverage + duplication
+
+#### ❌ Coverage on new code: 71% (gate requires ≥ 80%)
+- **Where:** `src/jobs/export.ts` — 47/82 new lines covered; `src/api/checkout.ts` — 31/40 new lines covered.
+- **Why it matters:** The two uncovered branches in `export.ts` are the error paths (lines 55–62, 71–78) — exactly where regressions hide.
+- **Fix:** Add three tests — happy path is covered; add cases for (a) upstream API 500, (b) empty result set, (c) `userPath` failing validation.
+
+## Pre-existing issues in touched files (FYI — not blocking)
+
+{Issues that pre-date this branch but live in files you changed. For awareness; the gate doesn't enforce them.}
+
+- ⚪ `src/api/checkout.ts:102` — [`typescript:S3776`] Cognitive complexity 18 > 15 (existing).
+- ⚪ `src/api/checkout.ts:155` — [`typescript:S1192`] String literal `"USD"` duplicated 4 times (existing).
+
+## What's solid
+
+- {2–4 things the change got right — patterns that survived the scan cleanly. Not flattery; signal for what to preserve.}
+- New `parseDiscount` helper has 100% branch coverage and no findings — keep the test shape for the rest of the payment module.
+
+## Suggested order to address
+
+1. **Fix anything failing the quality gate** — blockers, new vulnerabilities, coverage shortfall. The PR can't merge until these are green.
+2. **Review the security hotspots** — mark each Safe / At Risk / Acknowledged in the Sonar UI. The gate counts them as unresolved until you do.
+3. **Major code smells**, prioritizing files in `src/api/` and `src/jobs/` over UI / config.
+4. **Minors and nits** if time permits, otherwise defer.
+
+---
+
+Full report: {sonar-host}/dashboard?id={project-key}&branch={branch}

package/skills/strategy-analysis/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: strategy-analysis
+description: Run a strategy framework — SWOT/TOWS, Porter's Five Forces, or PESTLE — on a product, company, or market question, choosing the right framework for the question and forcing every cell to carry evidence and a so-what. Use when the user asks for a SWOT, a competitive/market analysis, "should we enter this market", "what's our position against X", or a macro-environment scan.
+---
+
+# strategy-analysis
+
+Runs the classic strategy frameworks the way a good strategist does and a bad deck doesn't: the framework is chosen to fit the question, every cell carries evidence and an implication, and the output ends in ranked, committal so-whats — not a filled-in grid. The grid is the working, never the deliverable. Sibling of `tech-comparison-matrix` (tech selection between named options) and `business-case` (a costed invest/defer decision); this skill is for the strategic question *before* options are named.
+
+## How to respond
+
+1. **Classify the question, then pick ONE framework** (two only when the question genuinely spans both, and say why):
+
+   | The question is about… | Framework |
+   |---|---|
+   | Our position: what to exploit, fix, or defend, feeding a near-term decision | **SWOT → TOWS** (SWOT alone is banned — see step 3) |
+   | Industry attractiveness / profit pressure: "should we enter", "why are margins thin", "can we defend" | **Porter's Five Forces** |
+   | Macro environment: regulation, technology shifts, demographics affecting a multi-year bet | **PESTLE** |
+
+   The user asked for a framework by name and it fits → run it. It doesn't fit → say so in one line and run the fitting framework instead — the quality bar treats a misfit framework as a category error, and a "SWOT" request that's really "should we enter this market" is Five Forces work; run the requested framework only if the user insists after the flag. Portfolio-allocation questions across many products (BCG-matrix territory) → name it, note it needs per-product market-share and growth data, and run it only if that data is supplied.
+
+2. **Collect the evidence base before filling anything.** Name what is known `[data: …]`, reported `[reported by …]`, drawn from general market knowledge `[market: …]`, and assumed `[assumption]`. The `[market: …]` tag exists because on a short prompt most cells are filled from the model's own market knowledge — that's legitimate, but it must stay distinguishable from the user's facts and from guesses. Ask at most 2 questions, spent on the decision the analysis feeds ("what decision does this inform, and by when?") and the competitive set ("who do customers actually compare you to?"). No decision named → the analysis has no ranking criterion; get one before proceeding. Non-interactive run (no user to ask): derive the most plausible decision from the input, state it as `[assumption]` at the top, and rank against it; none derivable → emit `BLOCKED: need the decision this analysis feeds` rather than an unranked survey.
+
+3. **Fill the framework with cells that pass the three tests.** Every entry must be (a) **specific** — a competitor, number, or named capability, not a category; (b) **evidenced** — carrying one of the step-2 tags; (c) **consequential** — with a one-line "so:" implication. ✅ *"S: 4,000 paying tenants' workflow data no rival can train on `[data: billing]` — so: the switching cost is the moat to invest in"* — ❌ *"S: strong team"*. Framework-specific rules:
+   - **SWOT** never ships alone — cross it into **TOWS** actions: S×O (attack), S×T (defend), W×O (fix to unlock), W×T (the exposed flank, named honestly). The TOWS quadrants are the output; the SWOT grid is scaffolding.
+   - **Five Forces**: each force gets a pressure rating (🟥 high / 🟧 medium / 🟨 low) *with the mechanism* — who holds the power and why (concentration, switching costs, differentiation, substitutes' price-performance). Rate all five; "N/A" is not a rating. Complements/platforms noted where they change the picture.
+   - **PESTLE**: only factors that plausibly move *this* decision within its time horizon, each with direction, timeframe, and the exposed asset. Six sections of filler is the classic failure — 3 sharp factors beat 18 generic ones; empty letters say "no material factor identified".
+
+4. **Rank the implications and commit.** End with **Implications, ranked** — 3–5 entries ordered by impact on the named decision, each an action-shaped sentence with an owner-shaped subject: ✅ *"Price the enterprise tier before Q3: supplier power is rising (🟥) and the S×O attack window closes when the incumbent's contract cycle renews"*. Then a one-paragraph **verdict** answering the user's actual question, taking a side, and naming what evidence would change it.
+
+5. **Emit in one message**: evidence base (tag summary), the framework grid(s), ranked implications, verdict. Flag every `[assumption]` that appears in a top-3 implication — those are the validation targets. Hand off: options now named and comparable → `tech-comparison-matrix`; investment decision to cost → `business-case`; product direction to test → `prfaq`.
+
+## Quality bar
+
+- **The framework fits the question**, and the doc says why in one line. A SWOT that should have been Five Forces is a category error, not a style choice.
+- **Every cell passes specific/evidenced/consequential.** One untagged, implication-free cell is a defect; a grid of them is a horoscope.
+- **SWOT always arrives as TOWS.** Four lists with no crossings is inventory, not strategy.
+- **Every Five Forces rating names the mechanism.** "Rivalry: high" without who/why is a vibe with a color.
+- **The implications are ranked and action-shaped**, tied to the named decision — not "consider monitoring the competitive landscape".
+- **The verdict takes a side** and names what would change it. An analysis that ends "it depends" has refused its job.
+
+## When to use this skill
+
+- ✅ "Run a SWOT on our developer-tools product" (arrives as SWOT→TOWS)
+- ✅ "Should we enter the SMB payroll market?" / "why are margins compressing?"
+- ✅ "What macro trends threaten this 3-year platform bet?"
+- ✅ A strategy offsite needs a rigorous pre-read instead of a brainstorm
+
+## When NOT to use this skill
+
+- ❌ Choosing between named technologies or vendors — `tech-comparison-matrix`
+- ❌ A costed build/buy/defer decision — `business-case`
+- ❌ Testing a specific product concept — `prfaq`
+- ❌ Quarterly goal-setting — `okr-cascade`
+
+## Anti-patterns to avoid
+
+- ❌ **Framework theater.** Running all three frameworks "for completeness" — each unfits the others' question, and the reader drowns. One question, one framework, one verdict.
+- ❌ **Horoscope cells.** "Strength: experienced team. Weakness: limited resources. Opportunity: growing market." True of every company that ever existed, therefore informative about none.
+- ❌ **SWOT as the deliverable.** The four quadrants are raw material; the TOWS crossings are where a decision lives. Shipping the grid alone ships the homework, not the answer.
+- ❌ **Unranked implications.** Ten equal-weight bullets delegate the actual judgment to the reader — the ranking *is* the analysis.
+- ❌ **Threat inflation.** Every macro trend rated critical so nothing is. Severity must be calibrated to the named decision's time horizon and exposed assets.
+- ❌ **Evidence-free confidence.** A verdict resting on untagged claims. The tag discipline exists so the reader can see exactly which legs are load-bearing guesses.

package/skills/strategy-analysis/evals/eval_queries.json

@@ -0,0 +1,13 @@
+[
+  { "query": "Run a SWOT analysis on our product", "should_trigger": true },
+  { "query": "Should we enter the SMB payroll market?", "should_trigger": true },
+  { "query": "Do a Porter's Five Forces on the ride-sharing industry", "should_trigger": true },
+  { "query": "What macro trends could threaten our 3-year platform bet?", "should_trigger": true },
+  { "query": "Why are our margins compressing — analyze the competitive pressure", "should_trigger": true },
+  { "query": "I need a PESTLE analysis for the board offsite", "should_trigger": true },
+
+  { "query": "Compare Postgres vs DynamoDB for our new service", "should_trigger": false },
+  { "query": "Write a business case for acquiring this tooling vendor", "should_trigger": false },
+  { "query": "Write a PRFAQ for our new product idea", "should_trigger": false },
+  { "query": "Cascade our company OKRs down to the platform team", "should_trigger": false }
+]

package/skills/strategy-analysis/evals/evals.json

@@ -0,0 +1,36 @@
+{
+  "skill_name": "strategy-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Run a SWOT on our product: a developer-tools startup with 4,000 paying tenants, strong CI/CD integration data, a small sales team, and a well-funded incumbent (CircleCI) moving into our niche. The decision this feeds: where to focus the next two quarters.",
+      "assertions": [
+        "SWOT is crossed into TOWS quadrants (S×O, S×T, W×O, W×T) — the four raw lists are not the final output",
+        "Every cell is specific (names a competitor, number, or capability), carries an evidence tag ([data]/[reported]/[assumption]), and has a 'so:' implication",
+        "No horoscope cells like 'strong team' or 'growing market' without specifics",
+        "Implications section is ranked (3-5 entries) and each is action-shaped, tied to the two-quarter focus decision",
+        "A verdict paragraph takes a side and names what evidence would change it",
+        "Assumptions appearing in top-ranked implications are flagged as validation targets",
+        "A hand-off to tech-comparison-matrix, business-case, or prfaq is offered where apt"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Give me a SWOT to decide whether we should enter the SMB payroll market in Germany.",
+      "assertions": [
+        "The skill flags that market-entry attractiveness is a Five Forces question and suggests it before or instead of SWOT",
+        "If Five Forces is run, all five forces get a pressure rating with the mechanism (who holds power and why) — no force rated 'N/A'",
+        "The output ends with a committal verdict on entering, not 'it depends'"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "[Non-interactive run — no user available to answer questions] Run a Porter's Five Forces on the European ride-sharing market. This feeds our decision on whether to expand our driver-scheduling SaaS into that segment next year.",
+      "assertions": [
+        "The skill proceeds (the decision IS named in the input) instead of blocking",
+        "Assumptions replacing the capped clarifying questions (e.g. competitive set) are tagged [assumption] and stated at the top",
+        "Market facts drawn from general knowledge are tagged [market: ...], distinguishable from user-supplied facts and assumptions"
+      ]
+    }
+  ]
+}

package/skills/strategy-analysis/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "strategy-analysis",
+  "version": "0.1.0",
+  "description": "Run a strategy framework — SWOT/TOWS, Porter's Five Forces, or PESTLE — on a product, company, or market question, choosing the right framework for the question and forcing every cell to carry evidence and a so-what. Use when the user asks for a SWOT, a competitive/market analysis, \"should we enter this market\", \"what's our position against X\", or a macro-environment scan.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["business-case", "okr-cascade", "prfaq", "tech-comparison-matrix"],
+  "tags": ["strategy", "swot", "tows", "five-forces", "pestle", "competitive-analysis", "market-analysis"],
+  "model": { "tier": "heavy", "rationale": "Framework selection plus evidenced multi-factor judgment ending in a ranked, committal verdict. Cheaper models fill cells with generic filler, skip the TOWS crossings, and refuse to take a side. Never downgrade." }
+}

package/skills/success-metrics/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: success-metrics
+description: Define how a feature's success will be measured before it's built — one primary metric with target, timeframe, and baseline; guardrail and counter-metrics; an instrumentation plan naming every event; and a pre-committed decision rule for what happens if the target is missed. Use when the user asks "how do we know this worked", needs KPIs or success criteria for a feature, or wants a measurement/instrumentation plan before launch.
+---
+
+# success-metrics
+
+Answers "how will we know it worked?" *before* build, when the answer can still change what gets built — and makes the measurement honest by pre-committing the decision rule, naming the counter-metric that catches gaming, and writing the instrumentation plan so launch day isn't the day someone discovers no event fires. Expands the one-line success criteria in a `prd-draft` into the full measurement design.
+
+## How to respond
+
+1. **Extract the goal** from the PRD, brief, or conversation. Ask at most 2 questions, spent on **baseline** ("what's the number today, and where does it live?") and **decision authority** ("who acts if the target is missed?"). No goal articulated yet → stop and route to `prd-draft`; metrics for an unstated goal measure noise. Non-interactive run (no user to ask): a stated-but-vague goal gets sharpened and tagged `[assumption]`; no goal at all → emit `BLOCKED: need the feature's goal` — never invent one.
+
+2. **Pick exactly one primary metric.** More than one primary means none — when they diverge, nobody pre-agreed which wins. The primary is an **outcome the user experiences or the business banks**, not an output the team ships. ✅ *"Median support-ticket handle time"* — ❌ *"Number of dashboard features launched"* — ❌ *"Dashboard page views"* (attention is not outcome). Every other contender becomes a secondary, guardrail, or gets cut.
+
+3. **Give the primary its three numbers**: **baseline** (today's value + source; if unknown, the first milestone of the plan is *measuring it* — a target without a baseline is a guess about a guess), **target** (the value that means "worked"), **timeframe** (when judged, plus the patience window — how long after launch before the data is trusted: novelty effects, weekly cycles, cohort maturity).
+
+4. **Add leading indicators** — 2–3 metrics that move within days and plausibly predict the primary, each with its causal sentence: ✅ *"% of tickets where the agent opens the unified view — if agents don't adopt it, handle time can't drop"*. Leading indicators are for steering mid-flight; only the primary decides success.
+
+5. **Set guardrails and the counter-metric.** Guardrails: 2–4 things the feature must **not** degrade (error rate, page latency, adjacent-flow conversion, support volume), each with its current value and an alert threshold. For a **brand-new surface with no prior value** (e.g. the feature's own latency), the guardrail says "baseline measured in week 1, threshold set then" — the same escape hatch the primary metric gets; don't invent a current number that can't exist pre-launch. Counter-metric: the specific way the primary could be gamed, and the metric that catches it — ✅ *"Handle time could drop via premature ticket closure → watch reopen rate"*. A primary without a counter-metric invites exactly the behavior it can't see.
+
+6. **Write the instrumentation plan** — for every metric: the event name (consistent scheme, e.g. `domain.object.action`), its properties (incl. the dimensions you'll slice by: tenant, plan, platform), where it fires, and whether it **exists today or must be built**. The must-build list is a launch dependency, not a fast-follow: shipped-then-instrumented features have no week-one data and a contaminated baseline. Dashboard owner and review cadence named.
+
+7. **Pre-commit the decision rule.** One sentence, agreed before launch, naming the action: ✅ *"If primary improvement < 10% at day 60 with ≥70% agent adoption, we run the iteration review; < 10% with low adoption, we fix adoption first; guardrail breach at any point pauses rollout"*. Without it, every result becomes an argument and every miss becomes "directionally positive."
+
+8. **Emit with [`templates/metrics-plan.md`](templates/metrics-plan.md)** in one message: metric tree (primary → leading → guardrails/counter), the three numbers, instrumentation table, decision rule, and review cadence.
+
+## Useful references in this skill
+
+- [`templates/metrics-plan.md`](templates/metrics-plan.md) — the metric tree, instrumentation table, and decision-rule skeleton
+
+## Quality bar
+
+- **Exactly one primary metric**, and it's an outcome, not an output or a vanity count. The doc states why it was chosen over the runner-up.
+- **Baseline, target, timeframe all present** — or "measure baseline" is explicitly milestone 1. No target hangs in the air.
+- **Every metric maps to a named event** marked exists/must-build. A metric without an event is fiction with a chart placeholder.
+- **The counter-metric names the gaming path.** "Could this number improve while the user's life gets worse?" has a written answer.
+- **The decision rule is action-shaped and pre-committed** — who does what at which threshold — not "we'll review the data".
+- **Guardrails have current values and alert thresholds**, so "don't degrade X" is checkable, not sentimental.
+
+## When to use this skill
+
+- ✅ A PRD's goals need their full measurement design
+- ✅ "How do we know this feature worked?" / "define the KPIs for X"
+- ✅ Pre-launch instrumentation planning — what events must exist on day one
+- ✅ Retro-fitting honest metrics onto a feature that shipped without any
+
+## When NOT to use this skill
+
+- ❌ No goal exists yet — `prd-draft` first; metrics can't rescue an unstated goal
+- ❌ Org/quarterly OKR setting — this skill measures one feature, not a company
+- ❌ Analyzing results after the fact — this designs the measurement; analysis is a conversation with the data
+- ❌ A/B-test statistics (power, sample size) — name the need, hand to the data team; don't improvise math
+
+## Anti-patterns to avoid
+
+- ❌ **Twelve "key" metrics.** A dashboard where everything is key lets every outcome be declared a win. One primary; the rest serve it.
+- ❌ **Targets without baselines.** "Increase activation to 40%" — from what? If today is 38%, the feature is a rounding error wearing a goal.
+- ❌ **Vanity metrics as primary.** Page views, sign-ups, sessions — countable, reportable, and silent on whether anyone's life improved.
+- ❌ **Instrumentation as fast-follow.** "We'll add tracking next sprint" = no week-one data, contaminated baseline, and a success debate held on vibes.
+- ❌ **Post-hoc decision rules.** Deciding what the numbers must show *after* seeing them — the moment measurement becomes marketing.
+- ❌ **Ignoring the patience window.** Judging at day 7 what needs a 60-day cohort — novelty spikes and weekly cycles read as signal.
+- ❌ **Proxy laundering.** Using clicks as a proxy for value and then forgetting it's a proxy — label proxies as proxies, every time they're cited.

package/skills/success-metrics/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "How do we know this feature worked? Define the KPIs", "should_trigger": true },
+  { "query": "Set up success criteria and an instrumentation plan before we launch", "should_trigger": true },
+  { "query": "What should we measure to judge the new onboarding flow?", "should_trigger": true },
+  { "query": "Define the success metrics for this PRD's goals", "should_trigger": true },
+
+  { "query": "Cascade company OKRs down to the teams", "should_trigger": false },
+  { "query": "Analyze last month's launch results", "should_trigger": false },
+  { "query": "Design the eval harness for our LLM feature", "should_trigger": false },
+  { "query": "Calculate the sample size for this A/B test", "should_trigger": false }
+]

package/skills/success-metrics/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "success-metrics",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Define success metrics for this feature: a unified customer view for our support agents, merging tickets, orders, and chat history into one screen. Goal from the PRD: cut median ticket handle time. Current handle time lives in our Zendesk dashboard.",
+      "assertions": [
+        "Exactly one primary metric, and it is an outcome (handle time), not an output or vanity count — with the runner-up named and the choice justified",
+        "The primary has baseline (with source), target, and timeframe including a patience window — or measuring the baseline is explicitly milestone 1",
+        "2-3 leading indicators, each with a causal sentence",
+        "2-4 guardrails with current values and alert thresholds (or a week-1 baseline plan for brand-new surfaces)",
+        "A counter-metric names the specific gaming path (e.g. premature ticket closure → reopen rate)",
+        "Every metric maps to a named event marked exists/must-build, and must-build events are launch blockers",
+        "A pre-committed, action-shaped decision rule names who does what at which threshold"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "[Non-interactive run — no user available to answer questions] Define success metrics.",
+      "assertions": [
+        "No metrics are invented — with no goal stated, the output is BLOCKED: need the feature's goal",
+        "The BLOCKED output routes to prd-draft (or names the goal as what to rerun with)",
+        "No primary metric, instrumentation table, or decision rule appears"
+      ]
+    }
+  ]
+}

package/skills/success-metrics/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "success-metrics",
+  "version": "0.1.0",
+  "description": "Define how a feature's success will be measured before it's built — one primary metric with target, timeframe, and baseline; guardrail and counter-metrics; an instrumentation plan naming every event; and a pre-committed decision rule for what happens if the target is missed. Use when the user asks \"how do we know this worked\", needs KPIs or success criteria for a feature, or wants a measurement/instrumentation plan before launch.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["prd-draft"],
+  "tags": ["metrics", "kpi", "instrumentation", "measurement", "analytics", "success-criteria"],
+  "model": { "tier": "standard", "rationale": "Structured measurement design; the primary-metric and counter-metric choices need judgment but the template bounds it. Escalate via ambiguous-input when the goal itself is contested." }
+}